Perspective Correction¶

Transform detection coordinates and optionally images from a perspective view to a top-down orthographic view using perspective transformation, correcting camera angle distortions to enable accurate measurements, top-down analysis, and coordinate normalization for scenarios where objects are viewed at an angle (e.g., surveillance cameras, aerial imagery, or tilted camera setups).

How This Block Works¶

This block corrects perspective distortion by transforming coordinates from a perspective view (where objects appear smaller when further away and angles are distorted) to a top-down orthographic view (as if the camera were directly above the scene). The block:

1. Receives input data: images and/or detections (object detection or instance segmentation predictions), along with perspective polygons defining regions to transform
2. Processes perspective polygons:
3. Selects the largest polygon from provided polygons (if multiple are provided)
4. Sorts polygon vertices in clockwise order and orients them starting from the leftmost bottom vertex
5. Ensures proper polygon ordering for transformation matrix calculation
6. Optionally extends perspective polygons to contain all detections:
7. If extend_perspective_polygon_by_detections_anchor is set, extends the polygon to ensure all detection anchor points (or entire bounding boxes if "ALL" is specified) are contained within the polygon
8. Calculates extension amounts needed to contain detections outside the original polygon
9. Adjusts polygon vertices to create a larger region that encompasses all detections
10. Generates perspective transformation matrix:
11. Maps the source polygon (4 vertices in the perspective view) to a destination rectangle (top-down view) with specified width and height
12. Uses OpenCV's getPerspectiveTransform to compute the 3x3 transformation matrix
13. Handles extended dimensions when polygon extension is enabled
14. Applies perspective transformation to detections (if provided):
15. Transforms bounding box coordinates from perspective view to top-down coordinates
16. Transforms instance segmentation masks by converting masks to polygons, transforming polygon vertices, and converting back to masks in the new coordinate space
17. Transforms keypoint coordinates for keypoint detection predictions
18. Updates all coordinate data to reflect the corrected perspective
19. Optionally warps images (if warp_image is True):
20. Applies the perspective transformation to the entire image using OpenCV's warpPerspective
21. Produces a top-down view of the image with corrected perspective
22. Outputs the warped image at the specified transformed rectangle dimensions (plus any extensions)
23. Returns corrected outputs:
24. corrected_coordinates: Detections with transformed coordinates in the top-down coordinate space
25. warped_image: Perspective-corrected image (if image warping is enabled)
26. extended_transformed_rect_width and extended_transformed_rect_height: Final dimensions including any polygon extensions

The transformation effectively "unwarps" the perspective distortion, making coordinates and images appear as if viewed from directly above. This is useful for accurate measurements, area calculations, distance measurements, and spatial analysis where perspective distortion would otherwise introduce errors.

Common Use Cases¶

• Top-Down Analysis: Correct perspective distortion for top-down analysis and measurement (e.g., surveillance camera analysis, overhead view generation, top-down coordinate normalization), enabling top-down analysis workflows
• Accurate Measurements: Enable accurate distance, area, and size measurements by removing perspective distortion (e.g., measure object sizes in real-world units, calculate areas accurately, measure distances without distortion), enabling measurement workflows
• Spatial Analysis: Perform spatial analysis and coordinate-based operations on corrected coordinates (e.g., zone-based analysis, spatial tracking, coordinate-based filtering), enabling spatial analysis workflows
• Aerial and Overhead Imagery: Process aerial imagery or overhead camera feeds with perspective correction (e.g., drone imagery analysis, overhead camera processing, satellite image analysis), enabling aerial analysis workflows
• Quality Control and Inspection: Correct perspective for quality control and inspection workflows (e.g., manufacturing inspection, product quality checks, defect detection with accurate measurements), enabling quality control workflows
• Indoor Navigation and Mapping: Correct perspective for indoor navigation and mapping applications (e.g., floor plan generation, indoor mapping, navigation systems), enabling mapping workflows

Connecting to Other Blocks¶

This block receives images and/or detections and produces perspective-corrected outputs:

• After detection models to correct coordinates for accurate analysis (e.g., object detection with perspective correction, instance segmentation with corrected coordinates), enabling detection-to-correction workflows
• After zone or polygon definition blocks to use defined regions as perspective polygons (e.g., use polygon zones as perspective regions, apply correction to specific regions), enabling zone-to-correction workflows
• Before measurement blocks to enable accurate measurements on corrected coordinates (e.g., distance measurement with corrected coordinates, size measurement on top-down view, area calculation on corrected coordinates), enabling correction-to-measurement workflows
• Before analytics blocks to perform analytics on corrected coordinates (e.g., zone analytics with corrected coordinates, tracking with top-down view, path analysis with corrected paths), enabling correction-to-analytics workflows
• Before visualization blocks to visualize corrected coordinates and warped images (e.g., display top-down view, visualize corrected detections, show perspective-corrected results), enabling correction-to-visualization workflows
• In workflow outputs to provide perspective-corrected final outputs (e.g., top-down coordinate outputs, corrected detection outputs, warped image outputs), enabling correction-to-output workflows

Requirements¶

This block requires either images or predictions (detections) as input. The perspective_polygons parameter must contain at least one polygon with exactly 4 vertices defining the region to transform. Polygons can be provided as a list of 4 coordinate pairs [[x1, y1], [x2, y2], [x3, y3], [x4, y4]] or as NumPy arrays. If multiple polygons are provided, the largest polygon (by area) is selected for each batch element. The transformed_rect_width and transformed_rect_height parameters define the dimensions of the output top-down rectangle. The block uses OpenCV's perspective transformation functions, which require proper polygon ordering and valid coordinate data. If polygon extension is enabled, the output dimensions are automatically adjusted to include the extended regions.

Type identifier¶

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

Properties¶

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

Available Connections¶

Input and Output Bindings¶

The available connections depend on its binding kinds. Check what binding kinds Perspective Correction in version v1 has.

{
    "name": "<your_step_name_here>",
    "type": "roboflow_core/perspective_correction@v1",
    "predictions": "$steps.object_detection_model.predictions",
    "images": "$inputs.image",
    "perspective_polygons": "$steps.perspective_wrap.zones",
    "transformed_rect_width": 1000,
    "transformed_rect_height": 1000,
    "extend_perspective_polygon_by_detections_anchor": "CENTER",
    "warp_image": false
}