Dynamic Crop¶

Class: DynamicCropBlockV1

Source: inference.core.workflows.core_steps.transformations.dynamic_crop.v1.DynamicCropBlockV1

Extract cropped image regions from input images based on bounding boxes from detection model predictions, supporting object detection, instance segmentation, and keypoint detection models with optional background removal using segmentation masks for focused region extraction and multi-stage analysis workflows.

How This Block Works¶

This block crops rectangular regions from input images using bounding boxes from detection model outputs, producing individual cropped images for each detected object. The block:

Receives input images and detection predictions (object detection, instance segmentation, or keypoint detection) containing bounding boxes
Validates that predictions contain detection IDs required for crop tracking
Extracts each bounding box from the predictions and crops the corresponding rectangular region from the input image
For instance segmentation predictions with mask_opacity > 0: Applies background removal by overlaying the segmentation mask, replacing background pixels outside the detected instance with the specified background_color and blending with the original crop based on mask opacity
Creates cropped image objects with metadata tracking the crop's origin (original image, offset coordinates, detection ID)
Translates prediction coordinates from the original image space to the cropped region space (adjusts bounding boxes, masks, keypoints, and polygons to be relative to the crop origin)
Returns a list of results for each detection, each containing the cropped image and the translated predictions

The block processes each detection's bounding box independently, creating separate crops for each detected object. For instance segmentation predictions, the optional background removal feature uses the segmentation mask to isolate the detected object from background pixels, useful for creating clean object-focused crops. All prediction coordinates (bounding boxes, keypoints, polygons, mask coordinates) are automatically translated to be relative to the cropped region's top-left corner, ensuring downstream blocks can process the crops correctly. The block increases output dimensionality by one (produces a list of crops per input image), enabling batch processing workflows where each crop can be processed independently.

Common Use Cases¶

Multi-Stage Object Analysis: Extract individual object crops from full images for detailed analysis (e.g., detect objects in a scene, crop each detected object, then run OCR or classification on individual crops), enabling focused analysis of specific regions without processing entire images
Background Removal for Object Focus: Create clean object crops with background removed using segmentation masks (e.g., detect and segment objects, crop with background removal, create isolated object images for training or analysis), enabling focused object extraction and cleaner downstream processing
Region-Based Processing Pipelines: Extract regions of interest for specialized processing (e.g., detect text regions, crop each text region, run OCR on crops; detect faces, crop each face, run face recognition), enabling efficient processing of specific image regions
Keypoint and Annotation Preservation: Extract object crops while preserving detection annotations (e.g., detect objects with keypoints, crop objects maintaining keypoint coordinates, analyze keypoints in cropped context), enabling focused analysis with full annotation context
Batch Region Extraction: Extract multiple regions from single images for parallel processing (e.g., detect all objects in image, crop each object separately, process crops in parallel for classification or analysis), enabling efficient batch processing of multiple regions
Training Data Preparation: Create cropped object datasets from annotated images (e.g., detect objects with bounding boxes, crop each object individually, export crops for training data collection), enabling automated extraction of training samples from full images

Connecting to Other Blocks¶

This block receives images and detection predictions, producing cropped images:

After detection blocks (e.g., Object Detection, Instance Segmentation, Keypoint Detection) to extract individual object regions based on detected bounding boxes, enabling focused analysis of detected objects in isolation
Before classification or analysis blocks that need object-focused inputs (e.g., OCR for text regions, fine-grained classification for cropped objects, detailed feature extraction), enabling specialized processing of individual regions rather than full images
In multi-stage detection workflows where initial detections are used to extract regions for secondary analysis (e.g., detect vehicles, crop each vehicle, detect license plates in crops), enabling hierarchical detection and analysis pipelines
Before visualization blocks that display individual objects (e.g., display cropped objects separately, create galleries of detected objects, show isolated object annotations), enabling focused visualization of extracted regions
After detection blocks with instance segmentation to create clean object crops with background removal, enabling isolated object images for analysis, training, or presentation
In keypoint detection workflows where keypoint coordinates need to be preserved in cropped contexts (e.g., detect people with keypoints, crop each person, analyze pose in cropped images), enabling keypoint analysis in focused image regions

Type identifier¶

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

Properties¶

Name	Type	Description	Refs
`name`	`str`	Enter a unique identifier for this step..	❌
`mask_opacity`	`float`	Background removal opacity for instance segmentation crops (0.0 to 1.0). Only applies when predictions contain segmentation masks (instance segmentation predictions). Controls how aggressively background pixels outside the detected instance are removed: 0.0 leaves the crop unchanged (no background removal), 1.0 fully replaces background with background_color, values between blend the original crop with the background. Higher values create cleaner object-focused crops. Set to 0.0 to disable background removal. Requires instance segmentation predictions with masks..	✅
`background_color`	`Union[Tuple[int, int, int], str]`	Background color to use when removing background from instance segmentation crops. Only applies when mask_opacity > 0 and predictions contain segmentation masks. Background pixels outside the detected instance mask are replaced with this color. Can be specified as: hex string (e.g., '#431112' or '#fff'), RGB string in parentheses (e.g., '(128, 32, 64)'), or RGB tuple (e.g., (18, 17, 67)). Defaults to black (0, 0, 0). Use white (255, 255, 255) or '#ffffff' for white backgrounds, or match your use case's background requirements. Color values are interpreted as RGB and converted to BGR for image processing..	✅

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 Crop in version v1.

Input and Output Bindings¶

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

Bindings

input
- images (image): Input image(s) to extract cropped regions from. Can be a single image or batch of images. Each image will be processed with corresponding detection predictions to extract bounding box regions. Cropped regions are extracted based on bounding boxes in the predictions. Can also accept previously cropped images from another Dynamic Crop step for nested cropping workflows..
- predictions (Union[keypoint_detection_prediction, object_detection_prediction, instance_segmentation_prediction]): Detection model predictions containing bounding boxes that define regions to crop from the images. Supports object detection (bounding boxes), instance segmentation (bounding boxes with segmentation masks), or keypoint detection (bounding boxes with keypoints) predictions. Each bounding box in the predictions defines a rectangular region to extract. Predictions must include detection IDs for crop tracking. Multiple detections per image result in multiple crops per image..
- mask_opacity (float_zero_to_one): Background removal opacity for instance segmentation crops (0.0 to 1.0). Only applies when predictions contain segmentation masks (instance segmentation predictions). Controls how aggressively background pixels outside the detected instance are removed: 0.0 leaves the crop unchanged (no background removal), 1.0 fully replaces background with background_color, values between blend the original crop with the background. Higher values create cleaner object-focused crops. Set to 0.0 to disable background removal. Requires instance segmentation predictions with masks..
- background_color (Union[rgb_color, string]): Background color to use when removing background from instance segmentation crops. Only applies when mask_opacity > 0 and predictions contain segmentation masks. Background pixels outside the detected instance mask are replaced with this color. Can be specified as: hex string (e.g., '#431112' or '#fff'), RGB string in parentheses (e.g., '(128, 32, 64)'), or RGB tuple (e.g., (18, 17, 67)). Defaults to black (0, 0, 0). Use white (255, 255, 255) or '#ffffff' for white backgrounds, or match your use case's background requirements. Color values are interpreted as RGB and converted to BGR for image processing..
output
- crops (image): Image in workflows.
- predictions (Union[object_detection_prediction, instance_segmentation_prediction, keypoint_detection_prediction]): Prediction with detected bounding boxes in form of sv.Detections(...) object if object_detection_prediction or Prediction with detected bounding boxes and segmentation masks in form of sv.Detections(...) object if instance_segmentation_prediction or Prediction with detected bounding boxes and detected keypoints in form of sv.Detections(...) object if keypoint_detection_prediction.

Example JSON definition of step Dynamic Crop in version v1

{
    "name": "<your_step_name_here>",
    "type": "roboflow_core/dynamic_crop@v1",
    "images": "$inputs.image",
    "predictions": "$steps.my_object_detection_model.predictions",
    "mask_opacity": "<block_does_not_provide_example>",
    "background_color": "#431112"
}