> 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/shape-analysis/hull-convex.md).

# Hull Convex

This function block calculates a convex enclosing contour around a provided contour and returns visual and numeric results useful for shape analysis.

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

`Image` The source image used for visualization and measurements.

`Contour` The input contour (shape) to enclose with a convex hull.

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

`Image` The source image annotated with the original contour and its convex hull.

`Contour` The calculated convex hull contour returned as a shape.

`Center` The centroid position of the convex hull (x, y).

`Area` The area of the convex hull.

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

This function block has no interactive controls. It runs automatically when inputs are provided.

## 🎯 What it does <a href="#features" id="features"></a>

* Computes an enclosing convex hull for the provided contour.
* Draws both the original contour and the convex hull onto the image for clear visual comparison.
* Calculates the hull area and its centroid coordinates for downstream measurements or logic.
* Returns both annotated visual output and structured shape/measurement outputs for further processing.

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

1. Provide the original image into the `Image` input so the block can produce an annotated visual result.
2. Provide a detected contour into the `Contour` input to compute its convex hull.
3. Use the returned `Image` to preview hull vs original contour, use `Contour`/`Center`/`Area` for measurements, filtering, or reporting.

## 📊 Evaluation <a href="#evaluation" id="evaluation"></a>

When run, the block examines the provided contour, produces a convex hull shape, annotates the image with both shapes, computes the hull centroid and area, and outputs these four results: annotated image, hull contour, center point, and area.

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

* If you don't yet have a contour, use the `Find Contour` block or `Find Object` block to get contours from an image before feeding them into this block.
* To simplify complex contours before hull calculation, consider `Approximate Contour` to reduce point count and improve performance.
* Use `Minimum Rectangle`, `Minimum Circle`, or `Minimum Ellipse` after this block when you need alternative enclosing shapes or additional geometric descriptors.
* Preprocess the image with `Image Threshold`, `Image Adaptive Threshold`, or `Blur` to get cleaner contours for more reliable hull computation.
* Crop or focus analysis using `Image ROI`, `Image ROI Select`, or `Image ROI Polygon` so the contour extraction and hull calculation target the area of interest.
* Visualize results in a larger window using `Show Image` and save important frames with `Image Logger` or `Image Write` for documentation or offline review.

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

* If the output `Contour` is empty or the `Area` is zero: ensure the input `Contour` is valid and contains enough points. Use contour-producing blocks (`Find Contour`, `Find Object`) and verify their outputs.
* If annotations look misplaced after image scaling: ensure the same image dimensions are used throughout the pipeline (use `Image Resize` or `Image Resizer` consistently).
* If unwanted background shapes produce large hulls: try preprocessing (thresholding, blurring) and use ROI blocks to focus on the object of interest.