Skip to content

Dynamic Zone

Class: DynamicZonesBlockV1

Source: inference.core.workflows.core_steps.transformations.dynamic_zones.v1.DynamicZonesBlockV1

Generate simplified polygon zones from instance segmentation detections by converting masks to contours, computing convex hulls, reducing polygon vertices to a specified count using Douglas-Peucker approximation, optionally applying least squares edge fitting, and scaling polygons to create geometric zones based on detected object shapes for zone-based analytics, spatial filtering, and region-of-interest definition workflows.

How This Block Works

This block creates simplified polygon zones from instance segmentation detections by converting complex mask shapes into geometrically convex polygons with a specified number of vertices. The block:

  1. Receives instance segmentation predictions containing masks (polygon representations) for detected objects
  2. Converts masks to contours:
  3. Extracts contours from each detection mask using mask-to-polygon conversion
  4. Selects the largest contour from each detection (handles multiple contours per mask)
  5. Computes convex hull:
  6. Calculates the convex hull of the largest contour using OpenCV's convex hull algorithm
  7. Ensures the resulting polygon is geometrically convex (no inward-facing angles)
  8. Creates a simplified outer boundary that encompasses all points in the contour
  9. Simplifies polygon to required vertex count:
  10. Uses Douglas-Peucker polygon approximation algorithm to reduce vertices
  11. Iteratively adjusts epsilon parameter to achieve the target number of vertices
  12. Uses binary search to find the optimal epsilon value that produces the requested vertex count
  13. Handles convergence: if exact vertex count cannot be achieved, pads or truncates vertices
  14. Optionally applies least squares edge fitting:
  15. If apply_least_squares is enabled, refines polygon edges by fitting lines to original contour points
  16. Selects contour points between polygon vertices
  17. Optionally filters to midpoint fraction (e.g., uses only central portion of each edge) to avoid edge effects
  18. Fits least squares lines to selected contour points for each edge
  19. Calculates intersections of fitted lines to create refined vertex positions
  20. Produces a polygon that better aligns with the original contour shape
  21. Scales polygon (if scale_ratio != 1):
  22. Calculates polygon centroid (center of mass)
  23. Scales polygon relative to centroid by the specified scale ratio
  24. Expands or contracts polygon outward from center (scale > 1 expands, scale < 1 contracts)
  25. Useful for creating buffer zones or adjusting zone boundaries
  26. Updates detections with simplified polygons:
  27. Stores simplified polygons in detection metadata under the polygon key
  28. Regenerates masks from simplified polygons for updated detection representation
  29. Returns simplified zones and updated detections:
  30. zones: List of simplified polygons (one per detection) as coordinate lists
  31. predictions: Updated detections with simplified polygons and masks
  32. simplification_converged: Boolean indicating if all polygons converged to exact vertex count

The block enables creation of geometric zones from complex object shapes detected by segmentation models. It's particularly useful when zones need to be created based on detected object shapes (e.g., basketball courts, road segments, parking lots, fields) where the zone should match the object's outline but be simplified for performance and ease of use.

Common Use Cases

  • Zone Creation from Detections: Create polygon zones based on detected object shapes (e.g., create basketball court zones from court detections, generate road segment zones from road detections, create field zones from sports field detections), enabling detection-based zone workflows
  • Geometric Zone Simplification: Simplify complex object shapes into geometrically convex polygons with controlled vertex counts (e.g., simplify irregular shapes to rectangles/quadrilaterals, reduce complex polygons to manageable vertex counts, create geometric zones from masks), enabling zone simplification workflows
  • Dynamic Zone Definition: Dynamically define zones based on detected objects in images (e.g., define zones from detected regions, create zones from object shapes, generate zones from segmentation results), enabling dynamic zone workflows
  • Zone-Based Analytics Setup: Prepare zones for zone-based analytics and filtering (e.g., prepare zones for time-in-zone analytics, create zones for zone-based filtering, set up zones for spatial analytics), enabling zone-based analytics workflows
  • Region-of-Interest Definition: Define regions of interest based on detected object boundaries (e.g., define ROIs from object detections, create ROI zones from segmentation, generate interest regions from masks), enabling ROI definition workflows
  • Spatial Filtering and Analysis: Create zones for spatial filtering and analysis operations (e.g., create zones for spatial filtering, prepare zones for area calculations, generate zones for spatial queries), enabling spatial analysis workflows

Connecting to Other Blocks

This block receives instance segmentation predictions and produces simplified polygon zones:

  • After instance segmentation models to create zones from detected object shapes (e.g., segmentation model to zones, masks to simplified polygons, detections to geometric zones), enabling segmentation-to-zone workflows
  • After detection filtering blocks to create zones from filtered detections (e.g., filter detections then create zones, create zones from specific classes, generate zones from filtered results), enabling filter-to-zone workflows
  • Before zone-based analytics blocks to provide simplified zones for analytics (e.g., zones for time-in-zone, zones for zone analytics, polygons for zone filtering), enabling zone-to-analytics workflows
  • Before visualization blocks to display simplified zones (e.g., visualize zone polygons, display geometric zones, show simplified regions), enabling zone visualization workflows
  • Before spatial filtering blocks to provide zones for spatial operations (e.g., zones for overlap filtering, polygons for spatial queries, regions for area calculations), enabling zone-to-filter workflows
  • In workflow outputs to provide simplified zones as final output (e.g., zone generation workflows, polygon extraction workflows, geometric zone outputs), enabling zone output workflows

Requirements

This block requires instance segmentation predictions with masks (polygon data). Input detections should be filtered to contain only the desired classes of interest before processing. The required_number_of_vertices parameter specifies the target vertex count for simplified polygons (e.g., 4 for rectangles/quadrilaterals, 3 for triangles). The block uses iterative Douglas-Peucker approximation with binary search to achieve the target vertex count, with a maximum of 1000 iterations. If convergence to exact vertex count fails, vertices are padded or truncated. The scale_ratio parameter (default 1) scales polygons relative to their centroid. The apply_least_squares parameter (default False) enables edge fitting to better align polygon edges with original contours. The midpoint_fraction parameter (0-1, default 1) controls which portion of contour points are used for least squares fitting (1 = all points, lower values use central portions of edges). The block outputs simplified polygons as lists of coordinate pairs, updated detections with simplified polygons, and a convergence flag.

Type identifier

Use the following identifier in step "type" field: roboflow_core/dynamic_zone@v1to add the block as as step in your workflow.

Properties

Name Type Description Refs
name str Enter a unique identifier for this step.. ❌
required_number_of_vertices int Target number of vertices for simplified polygons. The block uses Douglas-Peucker polygon approximation with iterative binary search to reduce polygon vertices to this count. Common values: 4 for rectangles/quadrilaterals, 3 for triangles, 6+ for more complex shapes. The algorithm attempts to converge to this exact count; if convergence fails (within iteration limit), vertices are padded or truncated to match the count.. ✅
scale_ratio float Scale factor to expand or contract resulting polygons relative to their centroid. Values > 1 expand polygons outward from center (create buffer zones), values < 1 contract polygons inward. Value of 1 (default) means no scaling. Scaling is applied after polygon simplification. Useful for creating buffer zones or adjusting zone boundaries.. ✅
apply_least_squares bool If True, applies least squares line fitting to refine polygon edges by aligning them with original contour points. For each edge of the simplified polygon, fits a line to contour points between vertices, then calculates intersections of fitted lines to create refined vertex positions. Produces polygons that better match the original contour shape, especially useful when simplified polygon vertices don't align well with contour edges.. ✅
midpoint_fraction float Fraction (0-1) of contour points to use for least squares fitting on each edge. Value of 1 (default) uses all contour points between vertices. Lower values use only the central portion of each edge (e.g., 0.9 uses 90% of points, centered). Useful when convex polygon vertices are not well-aligned with edges, as it focuses fitting on the central portion of edges rather than edge effects near vertices. Only applies when apply_least_squares is True.. ✅

The Refs column marks possibility to parametrise the property with dynamic values available in workflow runtime. See Bindings for more info.

Available Connections

Compatible Blocks

Check what blocks you can connect to Dynamic Zone in version v1.

Input and Output Bindings

The available connections depend on its binding kinds. Check what binding kinds Dynamic Zone in version v1 has.

Bindings

  • input

    • predictions (instance_segmentation_prediction): Instance segmentation predictions containing masks (polygon data) for detected objects. Detections should be filtered to contain only desired classes of interest. Each detection's mask is converted to contours, and the largest contour is used to generate a simplified polygon zone. Supports instance segmentation format with mask data..
    • required_number_of_vertices (integer): Target number of vertices for simplified polygons. The block uses Douglas-Peucker polygon approximation with iterative binary search to reduce polygon vertices to this count. Common values: 4 for rectangles/quadrilaterals, 3 for triangles, 6+ for more complex shapes. The algorithm attempts to converge to this exact count; if convergence fails (within iteration limit), vertices are padded or truncated to match the count..
    • scale_ratio (float): Scale factor to expand or contract resulting polygons relative to their centroid. Values > 1 expand polygons outward from center (create buffer zones), values < 1 contract polygons inward. Value of 1 (default) means no scaling. Scaling is applied after polygon simplification. Useful for creating buffer zones or adjusting zone boundaries..
    • apply_least_squares (boolean): If True, applies least squares line fitting to refine polygon edges by aligning them with original contour points. For each edge of the simplified polygon, fits a line to contour points between vertices, then calculates intersections of fitted lines to create refined vertex positions. Produces polygons that better match the original contour shape, especially useful when simplified polygon vertices don't align well with contour edges..
    • midpoint_fraction (float_zero_to_one): Fraction (0-1) of contour points to use for least squares fitting on each edge. Value of 1 (default) uses all contour points between vertices. Lower values use only the central portion of each edge (e.g., 0.9 uses 90% of points, centered). Useful when convex polygon vertices are not well-aligned with edges, as it focuses fitting on the central portion of edges rather than edge effects near vertices. Only applies when apply_least_squares is True..

  • output

Example JSON definition of step Dynamic Zone in version v1 
{
    "name": "<your_step_name_here>",
    "type": "roboflow_core/dynamic_zone@v1",
    "predictions": "$steps.instance_segmentation_model.predictions",
    "required_number_of_vertices": 4,
    "scale_ratio": 1.0,
    "apply_least_squares": false,
    "midpoint_fraction": 1.0
}