> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/workflows/ko/blocks/blocks/classical-computer-vision/mask-area-measurement.md).

# 마스크 면적 측정

검출된 객체의 면적을 측정합니다. 인스턴스 세분화 마스크의 경우, 면적은 0이 아닌 마스크 픽셀 수를 세어 계산합니다(구멍도 올바르게 처리). 바운딩 박스만 있는 검출의 경우, 면적은 너비에 높이를 곱한 값입니다. 필요에 따라 픽셀 면적을 실제 세계 단위로 변환하기 위해 `pixels_per_unit` 보정 값.

## 이 블록의 작동 방식

이 블록은 각 검출 객체의 면적을 계산하고, 검출마다 두 값을 저장합니다:

* **`area_px`** - 제곱 픽셀 단위의 면적(항상 계산됨)
* **`area_converted`** - 실제 세계 단위의 면적: `area_px / (pixels_per_unit ** 2)` (다음과 같음 `area_px` 때 `pixels_per_unit` 가 1.0일 때)

두 값은 각 검출에 첨부되고 직렬화된 JSON 출력에 포함됩니다. 이 블록은 이 필드들이 추가된 입력 검출을 반환하므로, 후속 블록(예: 레이블 시각화)이 면적 값을 표시할 수 있습니다.

### 면적 계산

이 블록은 수신하는 예측의 유형에 따라 두 가지 모드로 동작합니다:

1. **마스크 픽셀 면적(인스턴스 세분화)**: 입력 검출에 세분화 마스크가 포함되어 있는 경우, 이 블록은 다음을 사용해 각 마스크의 0이 아닌 픽셀 수를 셉니다 `cv2.countNonZero`. 이렇게 하면 구멍이 있는 마스크도 올바르게 처리됩니다. 구멍 픽셀은 0이며 계산에서 제외됩니다.
2. **바운딩 박스 면적(객체 검출)**: 세분화 마스크를 사용할 수 없는 경우, 이 블록은 면적을 바운딩 박스의 너비 × 높이(`w * h`).

### 단위 변환

다음을 `pixels_per_unit` 입력하여 픽셀 면적을 실제 세계 단위(예: cm², in², mm²)로 변환하세요. 면적은 2차원이므로, 변환 시 비율을 제곱합니다:

```
area_converted = area_px / (pixels_per_unit ** 2)
```

예를 들어, 보정값이 130 픽셀/cm라면, 다음과 같은 검출은 `area_px = 16900` 이 됩니다 `area_converted = 16900 / 16900 = 1.0 cm²`.

**pixels\_per\_unit를 결정하는 방법:** 카메라 시야에 알려진 크기의 물체(예: 자 또는 보정 타깃)를 놓습니다. 이미지에서 그 길이를 픽셀 단위로 측정한 후 실제 길이로 나눕니다. 예를 들어, 10 cm 기준 물체가 1300 픽셀에 걸쳐 있다면, `pixels_per_cm = 1300 / 10 = 130`. 만약 원근 보정을 사용 중이라면, 보정 물체는 원근 보정을 계산할 때 사용한 것과 같은 평면에 놓여 있어야 합니다.

## 일반적인 사용 사례

* **크기 기반 필터링**: 필터링 블록과 연결해 작은 노이즈 검출을 걸러내고, 최소 면적 임계값을 넘는 검출만 유지하세요.
* **품질 관리**: 측정된 면적을 예상 범위와 비교하여 제조 부품이 크기 사양을 충족하는지 확인합니다.
* **농업 분석**: 항공 이미지나 근접 촬영 이미지에서 잎 면적, 작물 피복률 또는 캐노피 범위를 측정합니다.
* **의료 영상**: 상처, 병변 또는 해부학적 구조의 면적을 정량화합니다. 다음을 사용해 `pixels_per_unit` 임상 문서화를 위한 실제 세계 측정값을 얻으세요.

## 다른 블록에 연결하기

* **상위 -- 객체 탐지 및 분할 모델**: 객체 탐지 또는 인스턴스 분할 모델의 출력을 `예측` 입력에 연결합니다. 인스턴스 분할 모델(마스크를 생성함)은 바운딩 박스만 있는 검출보다 더 정확한 면적 측정을 제공합니다.
* **상위 -- 카메라 보정 블록**: 사용 `roboflow_core/camera_calibration@v1` 검출 전에 렌즈 왜곡을 보정하기 위해 상위에 연결합니다.
* **상위 -- 원근 보정 블록**: 사용 `roboflow_core/perspective_correction@v1` 경사진 이미지를 상단 시점으로 변환해 면적 측정이 실제 객체의 점유 면적을 반영하도록 상위에 연결합니다.
* **하위 -- 시각화**: 출력 `예측` 을 레이블 또는 다각형 시각화 블록에 전달하세요.  `area_px` 및 `area_converted` 필드를 레이블로 표시할 수 있습니다.
* **하위 -- 필터링 블록**: 면적이 임계값을 충족하는 검출만 유지하도록 향상된 검출을 필터링 블록과 함께 사용하세요.

## 요구 사항

이 블록은 객체 탐지 또는 인스턴스 분할 모델의 검출 예측을 필요로 합니다. OpenCV와 NumPy(추론에 포함됨) 외에 추가 환경 변수, API 키 또는 외부 종속성은 필요하지 않습니다. 가장 정확한 면적 측정을 위해서는 객체별 마스크를 생성하는 인스턴스 분할 모델을 사용하세요.

### 유형 식별자

단계에서 다음 식별자를 사용하세요 `"type"` 필드: `roboflow_core/mask_area_measurement@v1` 워크플로우에 이 블록을 단계로 추가하려면.

### 속성

| **이름**            | **유형**  | **설명**                                                                                                                                       | 참조 |
| ----------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| `name`            | `str`   | 이 단계에 대한 고유 식별자를 입력하세요..                                                                                                                     | ❌  |
| `pixels_per_unit` | `float` | 실제 세계 길이 단위당 픽셀 수(예: cm당 픽셀 수). 변환된 면적은 area\_px / (pixels\_per\_unit \*\* 2)로 계산됩니다. 기본값 1.0은 변환 없음(area\_converted는 area\_px와 같음)을 의미합니다.. | ✅  |

이 **참조** 열은 워크플로우 런타임에서 사용 가능한 동적 값으로 속성을 매개변수화할 수 있는 가능성을 나타냅니다 `워크플로우` 런타임입니다. 자세한 내용은 *바인딩* 을 참조하세요.

### 입력 및 출력 바인딩

사용 가능한 연결은 바인딩 유형에 따라 달라집니다. 어떤 바인딩 유형인지 확인하세요 `마스크 영역 측정` 버전 `v1` 을 가지고 있는지.

<details>

<summary>입력 및 출력 바인딩</summary>

* 입력
  * `예측` (*Union\[*[*`object_detection_prediction`*](/workflows/ko/developer-guide/developer-guide/kinds/object-detection-prediction.md)*,* [*`instance_segmentation_prediction`*](/workflows/ko/developer-guide/developer-guide/kinds/instance-segmentation-prediction.md)*]*): 면적을 측정할 검출 예측..
  * `pixels_per_unit` ([*`float`*](/workflows/ko/developer-guide/developer-guide/kinds/float.md)): 실제 세계 길이 단위당 픽셀 수(예: cm당 픽셀 수). 변환된 면적은 area\_px / (pixels\_per\_unit \*\* 2)로 계산됩니다. 기본값 1.0은 변환 없음(area\_converted는 area\_px와 같음)을 의미합니다..
* 출력
  * `예측` (*Union\[*[*`object_detection_prediction`*](/workflows/ko/developer-guide/developer-guide/kinds/object-detection-prediction.md)*,* [*`instance_segmentation_prediction`*](/workflows/ko/developer-guide/developer-guide/kinds/instance-segmentation-prediction.md)*]*): sv.Detections(...) 객체 형태의 탐지된 바운딩 박스 예측, 다음 경우 `object_detection_prediction` 또는 sv.Detections(...) 객체 형태의 탐지된 바운딩 박스 및 세그멘테이션 마스크 예측, 다음 경우 `instance_segmentation_prediction`.

</details>

<details>

<summary>예시 JSON 정의</summary>

```json
{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/mask_area_measurement@v1",
	    "predictions": "$steps.model.predictions",
	    "pixels_per_unit": 1.0
	}
```

</details>