[Good First Issue]: Extend Python API with ROIAlignRotated-15

[mitruska]

Context

Instead of doing C++ to Python bindings for each and every OpenVINO operator, we are using internal NodeFactory, which takes the name of the operator as an argument:

op = NodeFactory().create("ROIAlignRotated", *args, **kwargs)  # pseudocode

Such an API is counter intuitive for an end user, so we are also adding Python API with a proper, pythonic and clear functions. Those Python functions are just wrappers around NodeFactory object call, and their primary goal is to provide appropriate inputs docs and more pythonic API:

op = ops.roi_align_rotated(*args, **kwargs)  # pseudocode

This task regards adding such a Python API function for ROIAlignRotated-15 operator.

What needs to be done?

1. Extend Python API and Python compatibility API with ROIAlignRotated (operator should be added to the opset15/ops.py)
2. Add tests for both APIs
3. Create a PR

ROIAlignRotated is a similar op to ROIAlign, with some modifications to enable rotation.

Python API roi_align can be used as an example:

openvino/src/bindings/python/src/openvino/runtime/opset9/ops.py

Lines 97 to 141 in bc505ba

	def roi_align(
	data: NodeInput,
	rois: NodeInput,
	batch_indices: NodeInput,
	pooled_h: int,
	pooled_w: int,
	sampling_ratio: int,
	spatial_scale: float,
	mode: str,
	aligned_mode: Optional[str] = "asymmetric",
	name: Optional[str] = None,
	) -> Node:
	"""Return a node which performs ROIAlign operation.
	:param data: Input data.
	:param rois: RoIs (Regions of Interest) to pool over.
	:param batch_indices: Tensor with each element denoting the index of
	the corresponding image in the batch.
	:param pooled_h: Height of the ROI output feature map.
	:param pooled_w: Width of the ROI output feature map.
	:param sampling_ratio: Number of bins over height and width to use to calculate
	each output feature map element.
	:param spatial_scale: Multiplicative spatial scale factor to translate ROI coordinates.
	:param mode: Method to perform pooling to produce output feature map elements. Avaiable modes are:
	- 'max' - maximum pooling
	- 'avg' - average pooling
	:param aligned_mode: Specifies how to transform the coordinate in original tensor to the resized tensor.
	Mode 'asymmetric' is the default value. Optional. Avaiable aligned modes are:
	- 'asymmetric'
	- 'half_pixel_for_nn'
	- 'half_pixel'
	:param name: The optional name for the output node
	:return: The new node which performs ROIAlign
	"""
	inputs = as_nodes(data, rois, batch_indices, name=name)
	attributes = {
	"pooled_h": pooled_h,
	"pooled_w": pooled_w,
	"sampling_ratio": sampling_ratio,
	"spatial_scale": spatial_scale,
	"mode": mode,
	"aligned_mode": aligned_mode,
	}
	return _get_node_factory_opset9().create("ROIAlign", inputs, attributes)

Python API roi_align_rotated function should reflect ROIAlignRotated C++ constructor:

openvino/src/core/include/openvino/op/roi_align_rotated.hpp

Lines 20 to 39 in bc505ba

	/// \brief Constructs a ROIAlignRotated operation.
	/// \param input Input feature map {N, C, H, W}
	/// \param rois Regions of interest to pool over
	/// \param batch_indices Indices of images in the batch matching
	/// the number or ROIs
	/// \param pooled_h Height of the ROI output features
	/// \param pooled_w Width of the ROI output features
	/// \param sampling_ratio Number of sampling points used to compute
	/// an output element
	/// \param spatial_scale Spatial scale factor used to translate ROI coordinates
	///
	/// \param clockwise_mode If true, rotation angle is interpreted as clockwise, otherwise as counterclockwise
	ROIAlignRotated(const Output<Node>& input,
	const Output<Node>& rois,
	const Output<Node>& batch_indices,
	const int pooled_h,
	const int pooled_w,
	const int sampling_ratio,
	const float spatial_scale,
	const bool clockwise_mode);

Please see attached PR, this task is very similar to the linked Col2Im Python API.

Example Pull Requests

#24569

Resources

• ROIAlignRotated documentation
• Contribution guide
• How to test OpenVINO Python API
• What is OpenVINO?
• Blog post on contributing to OpenVINO
• User documentation
• Intel DevHub Discord channel - engage in discussions, ask questions and talk to OpenVINO developers

Contact points

@mitruska
@p-wysocki
@akuporos

Ticket

141569

[awayzjj]

.take

[github-actions]

Thank you for looking into this issue! Please let us know if you have any questions or require any help.

[hub-bla]

.take

[github-actions]

Thank you for looking into this issue! Please let us know if you have any questions or require any help.

[mitruska]

@hub-bla The PR #25755 has been merged, thank you for this contribution!
Feel free to take a look at Good First Issues Board and select your next assignment 🚀