> For the complete documentation index, see [llms.txt](https://docs.augelab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.augelab.com/function-blocks/blocks-reference/detections-shapes/detectors/measure-object-distance.md).

# Measure Object Distance

This block measures the distance between two occurrences of a target object found in a source image. It provides a visual preview with markers and numeric outputs for X, Y and Euclidean distances. Use it when you need quick spatial measurements between two similar objects in an image.

## 📥 Inputs <a href="#inputs" id="inputs"></a>

* `Main Image` The image where the two objects will be located and measured.
* `1st Object Image` A template image (example) of the first object to find.
* `2nd Object Image` A template image (example) of the second object to find.

## 📤 Outputs <a href="#outputs" id="outputs"></a>

* `Image Any` Visual result showing the measured objects and markers.
* `Distance` The computed Euclidean distance between the two detected object centers (displayed with chosen measure factor).
* `X Distance` Horizontal distance between the two detected centers.
* `Y Distance` Vertical distance between the two detected centers.

## 🕹️ Controls <a href="#controls" id="controls"></a>

* `Measure Factor` Enter a numeric factor to convert pixel distance to real-world units (e.g., mm per pixel).
* `Measured distance` Readout label showing the computed distance for quick reference.
* `Image Preview` Visual area that displays the input image and measurement markers.

## ⚙️ Running mechanism <a href="#running-mechanism" id="running-mechanism"></a>

When the block runs it searches the `Main Image` for matches to the two provided object examples, determines the center positions for each found object, and then calculates the X, Y and Euclidean distances between those centers. The measured distance is multiplied by the `Measure Factor` to provide results in the desired unit. A preview image is updated to show the detected positions and the measurement.

## ✨ Features <a href="#features" id="features"></a>

* Visual feedback with markers and annotated preview image for easy verification.
* Numeric outputs for precise measurement reporting and further processing.
* Lightweight control via a single `Measure Factor` input to convert pixels to real units.
* Resizable preview area for clearer inspection of results.

## 📝 Usage <a href="#usage" id="usage"></a>

1. Provide the scene image to `Main Image`.
2. Provide example images for the two objects to `1st Object Image` and `2nd Object Image` (these should represent what you expect to find).
3. Set `Measure Factor` to convert pixel distances to real units (leave as 1 if you want pixel units).
4. Run the flow and check the `Image Any` preview and the `Distance`, `X Distance`, `Y Distance` outputs.

## 💡 Tips and Tricks <a href="#tips-and-tricks" id="tips-and-tricks"></a>

* If templates are hard to match in the full scene, crop the area first with `Image ROI Select` to limit the search region and speed up matching.
* Use `Image Resizer` or `Image Resize` to standardize image sizes if templates were captured at a different resolution than the main image.
* Improve matching reliability by preprocessing with `Adjust Colors`, `Contrast Optimization`, or `Blur` to reduce noise and enhance features.
* To verify results visually, connect the `Image Any` output to `Show Image` so you can open the preview in a larger viewer.
* When measuring across multiple found pairs or tracking over time, save frames with `Image Logger` or export measurements via `CSV Export` for later analysis.
* If you already have detected rectangles from an object detector, you can combine this block with detection blocks (for example `Find Object` or object detection outputs) to localize templates more robustly before measuring.

## 🛠️ Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

* No objects found: make sure the example images closely resemble how the objects appear in the `Main Image` (similar scale, orientation and lighting). Consider using `Image Resize` or `Adjust Colors`.
* Incorrect distance scale: double-check the `Measure Factor` value. If you need an accurate real-world scale, measure a known reference object in pixels and derive the factor.
* Multiple or incorrect matches: crop the search area with `Image ROI Select` or increase contrast with `Contrast Optimization` to reduce false matches.
* Preview not updating: ensure a valid image is provided to `Main Image` and reopen the preview (for larger view use `Show Image`).