---
language:
- ko
library_name: transformers
tags:
- road-crack-detection
- semantic-segmentation
- pothole-detection
- object-detection
- image-classification
- orthophoto
- infrastructure
- segformer
- yolov8
- convnext
pipeline_tag: image-segmentation
license: apache-2.0
---

# Road Crack Analyzer PT

도로 정사영상(Orthophoto)에서 균열 및 포트홀을 자동 탐지/분석하기 위한 모델 가중치 모음입니다.

## 가중치 파일 구조

```
MhRnd/road-crack-analyzer-pt/
├── yolo_best_2.pt                                              # YOLOv8s 균열 탐지 (22MB)
├── conv_best.pth                                               # ConvNeXt-Tiny 분류기 (319MB)
├── segformer-b2-finetuned_orthophoto_gaussian_crack_0920_512/  # Segformer-B2 균열 (105MB)
│   ├── config.json
│   └── model.safetensors
├── segformer-b0-finetuned-pothole_0830_1024/                   # Segformer-B0 포트홀 (15MB)
│   ├── config.json
│   └── model.safetensors
└── segformer-b0-finetuned-ade-512-512/                         # Segformer Feature Extractor
    └── preprocessor_config.json
```

## 모델 구성

### 1. YOLO v8 - 균열 영역 탐지

| 항목 | 내용 |
|------|------|
| **파일명** | `yolo_best_2.pt` |
| **아키텍처** | YOLOv8s |
| **용도** | 패치 내 균열 영역 사전 필터링 (Object Detection) |
| **입력** | RGB 이미지 (imgsz=1920) |
| **학습 데이터** | 도로 정사영상 균열 바운딩 박스 |

### 2. Crack Segmentor - 균열 세그멘테이션

| 항목 | 내용 |
|------|------|
| **디렉토리** | `segformer-b2-finetuned_orthophoto_gaussian_crack_0920_512/` |
| **아키텍처** | SegformerForSemanticSegmentation (B2) |
| **Feature Extractor** | `segformer-b0-finetuned-ade-512-512/` |
| **입력** | RGB 패치 이미지 |
| **출력** | 세그멘테이션 마스크 (background=0, crack>0) |
| **학습 데이터** | 도로 정사영상 균열 마스크 (Gaussian augmentation 적용) |

```python
from transformers import SegformerForSemanticSegmentation, SegformerImageProcessor

model = SegformerForSemanticSegmentation.from_pretrained(
    "MhRnd/road-crack-analyzer-pt",
    subfolder="segformer-b2-finetuned_orthophoto_gaussian_crack_0920_512"
)
extractor = SegformerImageProcessor.from_pretrained(
    "MhRnd/road-crack-analyzer-pt",
    subfolder="segformer-b0-finetuned-ade-512-512"
)

inputs = extractor(images=patch, return_tensors="pt")
outputs = model(**inputs)
pred = nn.functional.interpolate(
    outputs.logits, size=(512, 512), mode="bilinear", align_corners=False
).argmax(dim=1)[0].numpy()
```

### 3. Pothole Segmentor - 포트홀 세그멘테이션

| 항목 | 내용 |
|------|------|
| **디렉토리** | `segformer-b0-finetuned-pothole_0830_1024/` |
| **아키텍처** | SegformerForSemanticSegmentation (B0) |
| **입력** | RGB 패치 이미지 (512x512 resize) |
| **출력** | 세그멘테이션 마스크 (background=0, pothole=255) |
| **min_bbox_size** | 50px |

```python
model = SegformerForSemanticSegmentation.from_pretrained(
    "MhRnd/road-crack-analyzer-pt",
    subfolder="segformer-b0-finetuned-pothole_0830_1024"
)
```

### 4. ConvNeXt Classifier - 균열 유형 분류

| 항목 | 내용 |
|------|------|
| **파일명** | `conv_best.pth` |
| **아키텍처** | ConvNeXt-Tiny |
| **용도** | 균열 유형 분류 (LC / TC / AC) |
| **입력** | 균열 crop 이미지 (256x256 resize, ImageNet 정규화) |
| **출력** | 3-class logits |
| **클래스** | 0: LC (종방향 균열), 1: TC (횡방향 균열), 2: AC (거북등 균열) |
| **체크포인트 키** | `checkpoint["model"]` |

```python
from huggingface_hub import hf_hub_download

path = hf_hub_download("MhRnd/road-crack-analyzer-pt", "conv_best.pth")
cls_model = convnext_tiny(num_classes=3)
checkpoint = torch.load(path, map_location=device, weights_only=False)
cls_model.load_state_dict(checkpoint["model"])
cls_model.eval()

transforms = T.Compose([
    T.Resize(256, interpolation=T.InterpolationMode.BICUBIC),
    T.ToTensor(),
    T.Normalize(IMAGENET_DEFAULT_MEAN, IMAGENET_DEFAULT_STD),
])

img = Image.fromarray(crack_crop).convert("RGB")
pred = torch.argmax(cls_model(transforms(img).unsqueeze(0)))
# 0: LC, 1: TC, 2: AC
```

## 파이프라인

```
입력 이미지
  |
패치 단위 슬라이딩 윈도우 (size=1024, stride=682)
  |-- [Crack Segmentor] Segformer-B2 균열 세그멘테이션
  |     +-- logits -> upsample 512x512 -> argmax -> resize
  |     +-- Contour 추출 (area > 100) -> Polygon + Buffer (40px)
  +-- [Pothole Segmentor] Segformer-B0 포트홀 세그멘테이션
       +-- resize 512x512 -> logits -> upsample -> argmax
       +-- Contour 추출 (bbox > 50px)
  |
Crack Polygon 병합 (unary_union)
  |
[ConvNeXt Classifier] 균열 유형 분류 (LC/TC/AC)
  |
폭/길이/면적 측정
  |
결과 출력
```

## 균열 유형 정의

| 코드 | 이름 | 설명 | 색상 (BGR) |
|------|------|------|-----------|
| **LC** | Longitudinal Crack | 종방향 균열 (도로 진행 방향) | (255, 0, 0) |
| **TC** | Transverse Crack | 횡방향 균열 (도로 직각 방향) | (0, 0, 255) |
| **AC** | Alligator Crack | 거북등 균열 (망상 균열) | (0, 255, 0) |
| **POT** | Pothole | 포트홀 | (255, 0, 255) |

## 분석 파라미터

| 파라미터 | 값 | 설명 |
|----------|-----|------|
| `size` | 1024 | 슬라이딩 윈도우 패치 크기 |
| `over` | 682 | 패치 stride (size / 1.5) |
| `buffer_size` | 40 | 균열 polygon buffer 크기 |
| `min_crack_area` | 100 | 최소 균열 contour 면적 |
| `min_pothole_bbox` | 50 | 최소 포트홀 바운딩 박스 크기 |

## 관련 레포지토리

| 레포 | 설명 |
|------|------|
| [road-crack-analysis](https://gitlab.poc.muhanit.kr/sba/road-crack-analysis) | 배치 분석 파이프라인 |
| [road-crack-analysis-api](https://gitlab.poc.muhanit.kr/sba/road-crack-analysis-api) | FastAPI 추론 서버 |

## Contact

- Organization: [MhRnd](https://huggingface.co/MhRnd)
- Company: [무한정보기술 (MUHAN Information Technology)](https://muhanit.kr/)
- Email: pyh5214@muhanit.kr