> 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/distance-measurement.md).

# 거리 측정

2D 평면에서 바운딩 박스 좌표를 사용해 감지된 두 객체 사이의 거리를 계산합니다. 지정한 축을 따라 수평 또는 수직 거리 측정을 지원하며, 두 가지 보정 방법(알려진 치수의 기준 객체 또는 픽셀-센티미터 비율)을 사용해 픽셀 거리를 실제 측정값으로 변환하여 공간 분석, 객체 간 간격 평가, 안전 모니터링, 측정 워크플로를 수행합니다.

## 이 블록의 작동 방식

이 블록은 바운딩 박스 위치를 분석하고 픽셀 거리를 실제 단위(센티미터)로 변환하여 두 감지된 객체 사이의 거리를 측정합니다. 이 블록은:

1. 이미지 내 객체에 대한 바운딩 박스와 클래스 이름을 포함한 감지 예측을 수신합니다
2. 클래스 이름(object\_1\_class\_name 및 object\_2\_class\_name)을 사용해 두 대상 객체를 식별합니다:
   * 모든 감지를 검색하여 지정된 클래스 이름과 일치하는 바운딩 박스를 찾습니다
   * 두 객체의 바운딩 박스 좌표(x\_min, y\_min, x\_max, y\_max)를 추출합니다
   * 감지 결과에서 두 객체가 모두 발견되었는지 검증합니다
3. 거리 측정을 위한 객체 위치를 검증합니다:
   * 바운딩 박스가 겹치는지 확인합니다(겹치면 거리는 0으로 설정됩니다)
   * 지정된 기준 축(수평 또는 수직)에서 객체 사이에 간격이 있는지 확인합니다
   * 객체가 겹치거나 선택한 축에 맞게 잘못 배치된 경우 거리를 0으로 반환합니다
4. 보정 방법을 결정하고 보정을 수행합니다:

   **기준 객체 보정의 경우:**

   * 알려진 실제 치수를 가진 기준 객체(reference\_object\_class\_name)를 감지 결과에서 검색합니다
   * 기준 객체의 바운딩 박스 좌표를 추출합니다
   * 기준 객체의 픽셀 치수(너비와 높이)를 측정합니다
   * 픽셀-센티미터 비율을 계산합니다:
     * 너비 비율: reference\_width\_pixels / reference\_width(cm)
     * 높이 비율: reference\_height\_pixels / reference\_height(cm)
   * 더 정확한 스케일링을 위해 너비와 높이 비율의 평균 픽셀 비율을 계산합니다
   * 평균 비율을 사용하여 모든 픽셀 측정값을 센티미터로 변환합니다

   **픽셀-센티미터 비율 보정의 경우:**

   * 제공된 pixel\_ratio를 직접 사용합니다(예: 100픽셀 = 1센티미터)
   * 비율을 적용해 픽셀 거리를 센티미터 거리로 변환합니다
   * 픽셀 대비 실제 세계의 스케일이 이미 알려져 있거나 보정된 경우에 적합합니다
5. 지정된 축을 따라 두 객체 사이의 픽셀 거리를 측정합니다:
   * **수직 거리의 경우**: Y축을 따라 거리를 계산합니다(수직 분리)
     * 바운딩 박스 사이의 수직 간격을 찾습니다
     * 위쪽 객체의 하단에서 아래쪽 객체의 상단까지의 거리(또는 그 반대)를 측정합니다
     * 실제 간격 거리를 찾기 위해 바운딩 박스 위치를 고려합니다
   * **수평 거리의 경우**: X축을 따라 거리를 계산합니다(수평 분리)
     * 바운딩 박스 사이의 수평 간격을 찾습니다
     * 왼쪽 객체의 오른쪽 가장자리에서 오른쪽 객체의 왼쪽 가장자리까지의 거리(또는 그 반대)를 측정합니다
     * 실제 간격 거리를 찾기 위해 바운딩 박스 위치를 고려합니다
6. 픽셀 거리를 센티미터 거리로 변환합니다:
   * 픽셀 거리를 픽셀-센티미터 비율(보정값)로 나눕니다
   * 실제 세계 거리 측정을 센티미터 단위로 산출합니다
7. 픽셀 거리와 센티미터 거리 값을 모두 반환합니다

이 블록은 원근 왜곡이 최소인 수직 카메라 시점(탑다운 또는 정면)을 가정하여 정확한 2D 거리 측정을 보장합니다. 거리는 객체 중심 사이의 대각선 거리가 아니라, 지정한 축(수평 또는 수직)을 따라 바운딩 박스 사이의 간격으로 측정됩니다. 보정 과정은 알려진 치수의 기준 객체(더 유연하며 다양한 스케일에서 동작) 또는 직접 픽셀 비율(더 간단하지만 사전 보정 필요)을 사용해 픽셀 측정값을 실제 단위로 변환합니다. 이를 통해 모니터링, 분석, 제어 애플리케이션을 위한 정확한 공간 측정이 가능해집니다.

## 일반적인 사용 사례

* **안전 모니터링**: 객체 간 거리를 측정하여 안전한 간격을 보장합니다(예: 사회적 거리두기를 위해 사람 사이의 거리 측정, 차량 간 간격 모니터링, 산업 현장에서 안전 간격 보장)하여 안전 모니터링 워크플로를 지원합니다
* **창고 관리**: 저장 및 물류에서 품목이나 객체 간 간격을 측정합니다(예: 패키지 사이 간격 측정, 선반 간격 평가, 객체 배치 모니터링)하여 창고 관리 워크플로를 지원합니다
* **품질 관리**: 제조 및 조립에서 객체의 간격과 배치를 검증합니다(예: 부품 간 간격 측정, 조립 라인 간격 확인, 배치 정확도 점검)하여 품질 관리 워크플로를 지원합니다
* **교통 분석**: 교통 모니터링에서 차량 또는 객체 간 거리를 측정합니다(예: 차량 간격 측정, 안전 추종 거리 평가, 교통 간격 모니터링)하여 교통 분석 워크플로를 지원합니다
* **소매 분석**: 소매 환경에서 제품 또는 고객 간 간격을 측정합니다(예: 선반 위 제품 간격 측정, 고객 간격 평가, 진열 배치 모니터링)하여 소매 분석 워크플로를 지원합니다
* **농업 모니터링**: 농작물, 식물 또는 농업 객체 간 간격을 측정합니다(예: 작물 간격 측정, 식물 간 간격 평가, 필드 배치 모니터링)하여 농업 모니터링 워크플로를 지원합니다

## 다른 블록에 연결하기

이 블록은 감지 예측을 수신하고 distance\_cm 및 distance\_pixel 값을 생성합니다:

* **객체 탐지 또는 인스턴스 분할 블록 이후** 감지된 객체 사이의 거리를 측정하기 위해(예: 감지된 객체 간 거리 측정, 감지로부터 간격 계산, 객체 관계 분석) 감지-측정 워크플로를 지원합니다
* **로직 블록 이전** Continue If처럼 거리 측정값을 기반으로 결정을 내리기 위해(예: 거리가 안전하면 계속 진행, 간격 요구사항에 따라 필터링, 거리 임계값을 사용해 결정) 거리 기반 결정 워크플로를 지원합니다
* **분석 블록 앞에** 객체 간 공간 관계를 분석하기 위해(예: 객체 간 간격 분석, 거리 측정 처리, 공간 데이터 작업) 공간 분석 워크플로를 지원합니다
* **알림 블록 앞에서** 거리가 임계값을 위반할 때 알리기 위해(예: 간격이 너무 좁을 때 알림 전송, 거리 위반 알림, 측정값에 기반해 작업 트리거) 거리 기반 알림 워크플로를 지원합니다
* **데이터 저장 블록 앞에서** 거리 측정값을 기록하기 위해(예: 거리 측정값 저장, 간격 데이터 로깅, 공간 지표 기록) 거리 측정 로깅 워크플로를 지원합니다
* **측정 파이프라인에서** 거리 계산이 더 큰 공간 분석 워크플로의 일부인 경우(예: 분석 파이프라인에서 거리 측정, 모니터링 시스템에서 간격 계산, 체인에서 공간 측정 처리) 공간 측정 파이프라인 워크플로를 지원합니다

## 요구 사항

이 블록은 바운딩 박스와 클래스 이름이 포함된 감지 예측을 필요로 합니다. 이미지는 원근 왜곡을 최소화하고 정확한 2D 거리 측정을 보장하기 위해 수직 카메라 시점(탑다운 또는 정면)에서 촬영되어야 합니다. 기준 객체 보정을 사용하는 경우, 알려진 치수를 가진 기준 객체가 감지 결과에 포함되어 있어야 합니다. 픽셀-센티미터 비율 보정을 사용하는 경우, 카메라 설정에 대한 픽셀 비율이 사전 보정되어 있거나 알려져 있어야 합니다. 객체는 겹치면 안 되며, 지정된 측정 축(수평 또는 수직)을 따라 간격이 있어야 합니다. 이 블록은 정확한 2D 측정을 위해 객체가 같은 평면에 있다고 가정합니다.

### 유형 식별자

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

### 속성

| **이름**                        | **유형**  | **설명**                                                                                                                                                                                                                                                                                                                                                                                      | 참조 |
| ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -- |
| `name`                        | `str`   | 이 단계에 대한 고유 식별자를 입력하세요..                                                                                                                                                                                                                                                                                                                                                                    | ❌  |
| `object_1_class_name`         | `str`   | 거리 측정의 첫 번째 객체 클래스 이름입니다. 감지 예측의 클래스 이름과 정확히 일치해야 합니다. 이 블록은 감지 결과에서 이 클래스 이름을 검색하고 거리 계산에 해당 바운딩 박스를 사용합니다. 예: 감지에 'person', 'car', 'bicycle'로 표시된 객체가 포함되어 있다면, 사람과 다른 객체 사이의 거리를 측정하려면 'person'을 사용합니다. 클래스 이름은 대소문자를 구분하며 정확히 일치해야 합니다..                                                                                                                                                | ❌  |
| `object_2_class_name`         | `str`   | 거리 측정의 두 번째 객체 클래스 이름입니다. 감지 예측의 클래스 이름과 정확히 일치해야 합니다. 이 블록은 감지 결과에서 이 클래스 이름을 검색하고 거리 계산에 해당 바운딩 박스를 사용합니다. 예: 감지에 'person', 'car', 'bicycle'로 표시된 객체가 포함되어 있다면, 다른 객체에서 사람까지의 거리를 측정하려면 'person'을 사용합니다. 클래스 이름은 대소문자를 구분하며 정확히 일치해야 합니다. 이 블록은 지정된 reference\_axis를 따라 object\_1과 object\_2 사이의 간격을 측정합니다..                                                                              | ❌  |
| `reference_axis`              | `str`   | 두 객체 사이의 거리를 측정할 축입니다. 옵션: 'horizontal'은 X축을 따라 거리를 측정하며(객체 사이의 좌우 간격, 객체가 나란히 있을 때 유용), 'vertical'은 Y축을 따라 거리를 측정합니다(객체 사이의 상하 간격, 객체가 세로로 쌓여 있을 때 유용). 거리는 선택한 축을 따라 바운딩 박스 사이의 간격으로 측정됩니다. 정확한 측정을 위해 객체는 이 축을 따라 간격이 있어야 하며(겹치면 안 됨), 객체 배치에 따라 선택하세요: 나란히 있는 객체는 horizontal, 세로로 쌓인 객체는 vertical..                                                                                     | ❌  |
| `calibration_method`          | `str`   | 픽셀 측정값을 실제 단위(센티미터)로 보정하는 방법입니다. 옵션: 'reference object'(이미지 내 알려진 치수의 기준 객체를 사용해 픽셀-센티미터 비율을 자동으로 계산하며, 다양한 스케일에서 더 유연함) 또는 'pixel to centimeter'(사전 보정된 픽셀 비율을 직접 사용하며 더 단순하지만 알려진 스케일이 필요함). 기준 객체 방법의 경우, 알려진 너비와 높이를 가진 기준 객체가 감지 결과에 포함되어 있어야 합니다. 픽셀 비율 방법의 경우, 사용 중인 카메라 설정에 대해 pixel\_ratio가 사전 보정되어 있어야 합니다..                                                                      | ❌  |
| `reference_object_class_name` | `str`   | 보정에 사용되는 기준 객체의 클래스 이름입니다(calibration\_method가 'reference object'인 경우에만 사용). 감지 예측의 클래스 이름과 정확히 일치해야 합니다. 기준 객체는 실제 세계 치수(reference\_width 및 reference\_height)를 알고 있어야 합니다. 이 블록은 기준 객체의 픽셀 치수를 측정하고 모든 거리 측정을 변환하기 위한 픽셀-센티미터 비율을 계산합니다. 기본값은 'reference-object'입니다. 기준 객체는 감지 결과에 포함되어 있어야 하며, 명확하게 보이고 올바르게 감지되어야 합니다..                                                                 | ✅  |
| `reference_width`             | `float` | 기준 객체의 실제 세계 너비(센티미터)입니다(calibration\_method가 'reference object'인 경우에만 사용). 0보다 커야 합니다. 이는 기준 객체의 실제 물리적 너비입니다. 이 블록은 기준 객체의 픽셀 너비를 측정하고 이 값으로 나누어 픽셀-센티미터 비율을 계산합니다. 최상의 결과를 위해 정확한 측정을 사용하세요. 예: 기준 객체가 너비 2.5cm의 카드라면 2.5를 사용합니다. reference\_width와 reference\_height는 각각의 너비 및 높이 비율을 계산하는 데 사용되며, 더 정확한 스케일링을 위해 평균화됩니다..                                                              | ✅  |
| `reference_height`            | `float` | 기준 객체의 실제 세계 높이(센티미터)입니다(calibration\_method가 'reference object'인 경우에만 사용). 0보다 커야 합니다. 이는 기준 객체의 실제 물리적 높이입니다. 이 블록은 기준 객체의 픽셀 높이를 측정하고 이 값으로 나누어 픽셀-센티미터 비율을 계산합니다. 최상의 결과를 위해 정확한 측정을 사용하세요. 예: 기준 객체가 높이 2.5cm의 카드라면 2.5를 사용합니다. reference\_width와 reference\_height는 각각의 너비 및 높이 비율을 계산하는 데 사용되며, 더 정확한 스케일링을 위해 평균화됩니다..                                                              | ✅  |
| `pixel_ratio`                 | `float` | 이미지의 픽셀-센티미터 변환 비율입니다(calibration\_method가 'pixel to centimeter'인 경우에만 사용). 0보다 커야 합니다. 이 값은 1센티미터에 해당하는 픽셀 수를 나타냅니다. 예: 100픽셀 = 1센티미터라면 100을 사용합니다. 이 블록은 픽셀 거리를 이 비율로 나누어 센티미터로 변환합니다. 이 비율은 사용 중인 카메라 설정, 촬영 거리, 이미지 해상도에 맞게 사전 보정되어 있어야 합니다. 일반적인 값은 카메라 거리와 해상도에 따라 10\~500 범위입니다. 비율이 높을수록 센티미터당 픽셀이 많고(객체가 더 크게 보이며, 카메라가 더 가까움), 비율이 낮을수록 센티미터당 픽셀이 적습니다(객체가 더 작게 보이며, 카메라가 더 멀음).. | ✅  |

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

### 입력 및 출력 바인딩

사용 가능한 연결은 바인딩 유형에 따라 달라집니다. 어떤 바인딩 유형인지 확인하세요 `거리 측정` 버전 `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)*]*): 이미지 내 객체에 대한 바운딩 박스와 클래스 이름을 포함한 감지 예측입니다. 측정할 두 객체(object\_1\_class\_name 및 object\_2\_class\_name)에 대한 감지가 포함되어야 하며, 선택적으로 기준 객체(기준 객체 보정 방법을 사용하는 경우)도 포함될 수 있습니다. 바운딩 박스는 객체 사이의 거리를 계산하는 데 사용됩니다. 객체 감지와 인스턴스 분할 예측이 모두 지원됩니다. 감지에는 객체를 식별하기 위한 class\_name 정보가 포함되어야 합니다..
  * `reference_object_class_name` ([*`string`*](/workflows/ko/developer-guide/developer-guide/kinds/string.md)): 보정에 사용되는 기준 객체의 클래스 이름입니다(calibration\_method가 'reference object'인 경우에만 사용). 감지 예측의 클래스 이름과 정확히 일치해야 합니다. 기준 객체는 실제 세계 치수(reference\_width 및 reference\_height)를 알고 있어야 합니다. 이 블록은 기준 객체의 픽셀 치수를 측정하고 모든 거리 측정을 변환하기 위한 픽셀-센티미터 비율을 계산합니다. 기본값은 'reference-object'입니다. 기준 객체는 감지 결과에 포함되어 있어야 하며, 명확하게 보이고 올바르게 감지되어야 합니다..
  * `reference_width` ([*`float`*](/workflows/ko/developer-guide/developer-guide/kinds/float.md)): 기준 객체의 실제 세계 너비(센티미터)입니다(calibration\_method가 'reference object'인 경우에만 사용). 0보다 커야 합니다. 이는 기준 객체의 실제 물리적 너비입니다. 이 블록은 기준 객체의 픽셀 너비를 측정하고 이 값으로 나누어 픽셀-센티미터 비율을 계산합니다. 최상의 결과를 위해 정확한 측정을 사용하세요. 예: 기준 객체가 너비 2.5cm의 카드라면 2.5를 사용합니다. reference\_width와 reference\_height는 각각의 너비 및 높이 비율을 계산하는 데 사용되며, 더 정확한 스케일링을 위해 평균화됩니다..
  * `reference_height` ([*`float`*](/workflows/ko/developer-guide/developer-guide/kinds/float.md)): 기준 객체의 실제 세계 높이(센티미터)입니다(calibration\_method가 'reference object'인 경우에만 사용). 0보다 커야 합니다. 이는 기준 객체의 실제 물리적 높이입니다. 이 블록은 기준 객체의 픽셀 높이를 측정하고 이 값으로 나누어 픽셀-센티미터 비율을 계산합니다. 최상의 결과를 위해 정확한 측정을 사용하세요. 예: 기준 객체가 높이 2.5cm의 카드라면 2.5를 사용합니다. reference\_width와 reference\_height는 각각의 너비 및 높이 비율을 계산하는 데 사용되며, 더 정확한 스케일링을 위해 평균화됩니다..
  * `pixel_ratio` ([*`float`*](/workflows/ko/developer-guide/developer-guide/kinds/float.md)): 이미지의 픽셀-센티미터 변환 비율입니다(calibration\_method가 'pixel to centimeter'인 경우에만 사용). 0보다 커야 합니다. 이 값은 1센티미터에 해당하는 픽셀 수를 나타냅니다. 예: 100픽셀 = 1센티미터라면 100을 사용합니다. 이 블록은 픽셀 거리를 이 비율로 나누어 센티미터로 변환합니다. 이 비율은 사용 중인 카메라 설정, 촬영 거리, 이미지 해상도에 맞게 사전 보정되어 있어야 합니다. 일반적인 값은 카메라 거리와 해상도에 따라 10\~500 범위입니다. 비율이 높을수록 센티미터당 픽셀이 많고(객체가 더 크게 보이며, 카메라가 더 가까움), 비율이 낮을수록 센티미터당 픽셀이 적습니다(객체가 더 작게 보이며, 카메라가 더 멀음)..
* 출력
  * `distance_cm` ([`정수`](/workflows/ko/developer-guide/developer-guide/kinds/integer.md)): 정수 값.
  * `distance_pixel` ([`정수`](/workflows/ko/developer-guide/developer-guide/kinds/integer.md)): 정수 값.

</details>

<details>

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

```json
{
	    "name": "<your_step_name_here>",
	    "type": "roboflow_core/distance_measurement@v1",
	    "predictions": "$steps.model.predictions",
	    "object_1_class_name": "car",
	    "object_2_class_name": "person",
	    "reference_axis": "vertical",
	    "calibration_method": "<block_does_not_provide_example>",
	    "reference_object_class_name": "reference-object",
	    "reference_width": 2.5,
	    "reference_height": 2.5,
	    "pixel_ratio": 100
	}
```

</details>