Shapes#

This module implements the Ellipse shape entity.

class otx.api.entities.shapes.ellipse.Ellipse(x1: float, y1: float, x2: float, y2: float, modification_date: Optional[datetime] = None)#

Ellipse represents an ellipse that is encapsulated by a Rectangle.

x1 and y1 represent the top-left coordinate of the encapsulating rectangle
x2 and y2 representing the bottom-right coordinate of the encapsulating rectangle

Args:: x1: left x coordinate of encapsulating rectangle y1: top y coordinate of encapsulating rectangle x2: right x coordinate of encapsulating rectangle y2: bottom y coordinate of encapsulating rectangle

modification_date: last modified date

denormalize_wrt_roi_shape(roi_shape: Rectangle) → Ellipse#

Transforming shape from the normalized coordinate system to the roi coordinate system.

This function is the inverse of normalize_wrt_roi_shape

Example:

Assume we have Ellipse c1 which lives in the top-right quarter of the normalized coordinate space. The roi is a rectangle living in the half right of the normalized coordinate space. This function returns Ellipse c1 expressed in the coordinate space of roi. (should return top-half)

Ellipse denormalized to a rectangle as ROI

>>> from otx.api.entities.annotation import Annotation
>>> from otx.api.entities.shapes.ellipse import Ellipse
>>> c1 = Ellipse(x1=0.5, x2=1.0, y1=0.0, y2=0.5)  # An ellipse in the top right
>>> roi = Rectangle(x1=0.5, x2=1.0, y1=0.0, y2=1.0)  # the half-right
>>> normalized = c1.denormalize_wrt_roi_shape(roi_shape)  # should return top half
>>> normalized
Ellipse(, x1=0.0, y1=0.0, x2=1.0, y2=0.5)

Args:

roi_shape: Region of Interest

Returns:

New polygon in the ROI coordinate system

get_area() → float#

Computes the approximate area of the Ellipse.

Area is a value between 0 and 1, computed as pi * vertex * co-vertex.

>>> Ellipse(x1=0, y1=0, x2=0.8, y2=0.4).get_area()
0.25132741228718347

Returns:: area of the shape

get_evenly_distributed_ellipse_coordinates(number_of_coordinates: int = 50) → List[Tuple[float, float]]#

Returns evenly distributed coordinates along the ellipse.

Makes use of scipy.special.ellipeinc() which provides the numerical integral along the perimeter of the ellipse, and scipy.optimize.root() for solving the equal-arcs length equation for the angles.

Args:

number_of_coordinates: number of evenly distributed points: to generate along the ellipsis line

Returns:

list of tuple’s with coordinates along the ellipse line

property height: float#

Returns the height [y-axis] of the ellipse.

Example:

>>> e1 = Ellipse(x1=0.5, x2=1.0, y1=0.0, y2=0.5)
>>> e1.height
0.5

Returns:: the height of the ellipse. (y-axis)

property major_axis: float#

Returns the major axis of the ellipse.

Example:

>>> e1 = Ellipse(x1=0.5, x2=1.0, y1=0.0, y2=0.4)
>>> e1.major_axis
0.25

Returns:: major axis of ellipse.

property minor_axis: float#

Returns the minor axis of the ellipse.

Example:

>>> e1 = Ellipse(x1=0.5, x2=1.0, y1=0.0, y2=0.4)
>>> e1.minor_axis
0.2

Returns:: minor axis of ellipse.

normalize_wrt_roi_shape(roi_shape: Rectangle) → Ellipse#

Transforms from the roi coordinate system to the normalized coordinate system.

This function is the inverse of denormalize_wrt_roi_shape.

Example:

Assume we have Ellipse c1 which lives in the top-right quarter of a 2D space. The 2D space where c1 lives in is an roi living in the top-left quarter of the normalized coordinate space. This function returns Ellipse c1 expressed in the normalized coordinate space.

>>> from otx.api.entities.annotation import Annotation
>>> from otx.api.entities.shapes.rectangle import Rectangle
>>> from otx.api.entities.shapes.ellipse import Ellipse
>>> c1 = Ellipse(x1=0.5, y1=0.5, x2=0.6, y2=0.6)
>>> roi = Rectangle(x1=0.0, x2=0.5, y1=0.0, y2=0.5)
>>> normalized = c1.normalize_wrt_roi_shape(roi_shape)
>>> normalized
Ellipse(, x1=0.25, y1=0.25, x2=0.3, y2=0.3)

Args:

roi_shape: Region of Interest

Returns:

New polygon in the image coordinate system

property width: float#

Returns the width [x-axis] of the ellipse.

Example:

>>> e1 = Ellipse(x1=0.5, x2=1.0, y1=0.0, y2=0.5)
>>> e1.width
0.5

Returns:: the width of the ellipse. (x-axis)

property x_center: float#: Returns the x coordinate in the center of the ellipse.

property y_center: float#: Returns the y coordinate in the center of the ellipse.

This module implements the Polygon Shape entity.

class otx.api.entities.shapes.polygon.Point(x: float, y: float)#

This class defines a Point with an X and Y coordinate.

Multiple points can be used to represent a Polygon

denormalize_wrt_roi_shape(roi_shape: Rectangle) → Point#

The inverse of normalize_wrt_roi_shape.

Transforming Polygon from the normalized coordinate system to the roi coordinate system. This is used to pull ground truth during training process of the tasks. Examples given in the Shape implementations.

Args:: roi_shape (Rectangle): the shape of the roi

normalize_wrt_roi(roi_shape: Rectangle) → Point#

The inverse of denormalize_wrt_roi_shape.

Transforming Polygon from the roi coordinate system to the normalized coordinate system. This is used when the tasks want to save the analysis results.

For example in Detection -> Segmentation pipeline, the analysis results of segmentation needs to be normalized to the roi (bounding boxes) coming from the detection.

Args:: roi_shape (Point): the shape of the roi

x#

y#

class otx.api.entities.shapes.polygon.Polygon(points: List[Point], modification_date: Optional[datetime] = None)#

Represents a polygon formed by a list of coordinates.

NB Freehand drawings are also stored as polygons.

Args:: points: list of Point’s forming the polygon modification_date: last modified date

denormalize_wrt_roi_shape(roi_shape: Rectangle) → Polygon#

Transforming shape from the normalized coordinate system to the roi coordinate system.

This function is the inverse of normalize_wrt_roi_shape

Example:

Assume we have Polygon p1 which lives in the top-right quarter of the normalized coordinate space. The roi is a rectangle living in the half right of the normalized coordinate space. This function returns Polygon p1 expressed in the coordinate space of roi. (should return top-half)

Polygon denormalized to a rectangle as ROI

>>> from otx.api.entities.shapes.rectangle import Rectangle
>>> from otx.api.entities.annotation import Annotation
>>> p1 = Polygon(points=[Point(x=0.5, y=0.0), Point(x=0.75, y=0.2), Point(x=0.6, y=0.1)])
>>> roi = Rectangle(x1=0.5, x2=1.0, y1=0.0, y2=1.0)  # the half-right
>>> normalized = p1.denormalize_wrt_roi_shape(roi_shape)
>>> normalized
Polygon(, len(points)=3)

Args:

roi_shape: Region of Interest

Returns:

New polygon in the ROI coordinate system

get_area() → float#

Returns the approximate area of the shape.

Area is a value between 0 and 1, computed by converting the Polygon to a shapely polygon and reading the .area property.

NOTE: This method should not be relied on for exact area computation. The area is approximate, because shapes are continuous, but pixels are discrete.

Example:

>>> Polygon(points=[Point(x=0.0, y=0.5), Point(x=0.5, y=0.5), Point(x=0.75, y=0.75)]).get_area()
0.0625

Returns:: area of the shape

normalize_wrt_roi_shape(roi_shape: Rectangle) → Polygon#

Transforms from the roi coordinate system to the normalized coordinate system.

This function is the inverse of denormalize_wrt_roi_shape.

Example:

Assume we have Polygon p1 which lives in the top-right quarter of a 2D space. The 2D space where p1 lives in is an roi living in the top-left quarter of the normalized coordinate space. This function returns Polygon p1 expressed in the normalized coordinate space.

>>> from otx.api.entities.annotation import Annotation
>>> from otx.api.entities.shapes.rectangle import Rectangle
>>> p1 = Polygon(points=[Point(x=0.5, y=0.0), Point(x=0.75, y=0.2), Point(x=0.6, y=0.1)])
>>> roi = Rectangle(x1=0.0, x2=0.5, y1=0.0, y2=0.5)
>>> normalized = p1.normalize_wrt_roi_shape(roi_shape)
>>> normalized
Polygon(, len(points)=3)

Args:

roi_shape: Region of Interest

Returns:

New polygon in the image coordinate system

This module implements the Rectangle shape entity.

class otx.api.entities.shapes.rectangle.Rectangle(x1: float, y1: float, x2: float, y2: float, modification_date: Optional[datetime] = None)#

Rectangle represents a rectangular shape.

Rectangle are used to annotate detection and classification tasks. In the classification case, the rectangle is a full rectangle spanning the whole related item (could be an image, video frame, a region of interest).

x1 and y1 represent the top-left coordinate of the rectangle
x2 and y2 representing the bottom-right coordinate of the rectangle

Args:: x1 (float): x-coordinate of the top-left corner of the rectangle y1 (float): y-coordinate of the top-left corner of the rectangle x2 (float): x-coordinate of the bottom-right corner of the rectangle y2 (float): y-coordinate of the bottom-right corner of the rectangle modification_date (datetime.datetime): Date of the last modification of the rectangle

clip_to_visible_region() → Rectangle#

Clip the rectangle to the [0, 1] visible region of an image.

Returns:: Rectangle: Clipped rectangle.

crop_numpy_array(data: ndarray) → ndarray#

Crop the given Numpy array to the region of interest represented by this rectangle.

Args:: data (np.ndarray): Image to crop.
Returns:: np.ndarray: Cropped image.

denormalize_wrt_roi_shape(roi_shape: ShapeEntity) → Rectangle#

Transforming shape from the normalized coordinate system to the roi coordinate system.

Example:

Assume we have rectangle b1 which lives in the top-right quarter of the normalized coordinate space. The roi is a rectangle living in the half right of the normalized coordinate space. This function returns rectangle b1 expressed in the coordinate space of roi. (should return top-half) Box denormalized to a rectangle as ROI
>>> from otx.api.entities.annotation import Annotation
>>> b1 = Rectangle(x1=0.5, x2=1.0, y1=0.0, y2=0.5)
# the top-right
>>> roi = Annotation(Rectangle(x1=0.5, x2=1.0, y1=0.0, y2=1.0))
# the half-right
>>> normalized = b1.denormalize_wrt_roi_shape(roi_shape)
# should return top half
>>> normalized
Box(, x=0.0, y=0.0, width=1.0, height=0.5)

Args:: roi_shape (ShapeEntity): Region of Interest
Raises:: ValueError: If the roi_shape is not a Rectangle.
Returns:: Rectangle: New polygon in the ROI coordinate system

property diagonal: float#

Returns the diagonal size/hypotenuse of the rectangle (x-axis).

Example:

>>> b1 = Rectangle(x1=0.0, x2=0.3, y1=0.0, y2=0.4)
>>> b1.diagonal
0.5

Returns:: float: the width of the rectangle. (x-axis)

classmethod generate_full_box() → Rectangle#

Returns a rectangle that fully encapsulates the normalized coordinate space.

Example:

>>> Rectangle.generate_full_box()
Box(, x=0.0, y=0.0, width=1.0, height=1.0)

Returns:

Rectangle: A rectangle that fully encapsulates the normalized coordinate space.

get_area() → float#

Computes the approximate area of the shape.

Area is a value between 0 and 1, calculated as (x2-x1) * (y2-y1)

NOTE: This method should not be relied on for exact area computation. The area is approximate, because shapes are continuous, but pixels are discrete.

Example:

>>> Rectangle(0, 0, 1, 1).get_area()
1.0
>>> Rectangle(0.5, 0.5, 1.0, 1.0).get_area()
0.25

Returns:

float: Approximate area of the shape.

property height: float#

Returns the height of the rectangle (y-axis).

Example:

>>> b1 = Rectangle(x1=0.5, x2=1.0, y1=0.0, y2=0.5)
>>> b1.height
0.5

Returns:: float: the height of the rectangle. (y-axis)

static is_full_box(rectangle: ShapeEntity) → bool#

Returns true if rectangle is a full box (occupying the full normalized coordinate space).

Example:

>>> b1 = Rectangle(x1=0.5, x2=1.0, y1=0.0, y2=1.0)
>>> Rectangle.is_full_box(b1)
False

>>> b2 = Rectangle(x1=0.0, x2=1.0, y1=0.0, y2=1.0)
>>> Rectangle.is_full_box(b2)
True

Args:: rectangle (ShapeEntity): rectangle to evaluate
Returns:: bool: true if it fully encapsulate normalized coordinate space.

normalize_wrt_roi_shape(roi_shape: ShapeEntity) → Rectangle#

Transforms from the roi coordinate system to the normalized coordinate system.

Example:

Assume we have rectangle b1 which lives in the top-right quarter of a 2D space. The 2D space where b1 lives in is an roi living in the top-left quarter of the normalized coordinate space. This function returns rectangle b1 expressed in the normalized coordinate space.

>>> from otx.api.entities.annotation import Annotation
>>> b1 = Rectangle(x1=0.5, x2=1.0, y1=0.0, y2=0.5)
>>> roi = Rectangle(x1=0.0, x2=0.5, y1=0.0, y2=0.5)
>>> normalized = b1.normalize_wrt_roi_shape(roi_shape)
>>> normalized
Box(, x=0.25, y=0.0, width=0.25, height=0.25)

Args:

roi_shape (ShapeEntity): Region of Interest.

Raises:

ValueError: If the roi_shape is not a Rectangle.

Returns:

New polygon in the image coordinate system

property width: float#

Returns the width of the rectangle (x-axis).

Example:

>>> b1 = Rectangle(x1=0.5, x2=1.0, y1=0.0, y2=0.5)
>>> b1.width
0.5

Returns:: float: the width of the rectangle. (x-axis)

This file defines the ShapeEntity interface and the Shape abstract class.

exception otx.api.entities.shapes.shape.GeometryException#: Exception that is thrown if the geometry of a Shape is invalid.

class otx.api.entities.shapes.shape.Shape(shape_type: ShapeType, modification_date: datetime)#

Base class for Shape entities.

contains_center(other: ShapeEntity) → bool#

Checks whether the center of the ‘other’ shape is located in the shape.

Args:: other (ShapeEntity): Shape to compare with.
Returns:: bool: Boolean that indicates whether the center of the other shape is located in the shape

get_area() → float#: Get the area of the shape.

intersects(other: Shape) → bool#: Returns True, if other intersects with shape, otherwise returns False.

class otx.api.entities.shapes.shape.ShapeEntity(shape_type: ShapeType)#

This interface represents the annotation shapes on the media given by user annotations or system analysis.

The shapes is a 2D geometric shape living in a normalized coordinate system (the values range from 0 to 1).

abstract contains_center(other: ShapeEntity) → bool#

Checks whether the center of the ‘other’ shape is located in the shape.

Args:: other (ShapeEntity): Shape to compare with
Returns:: bool: true if the center of the ‘other’ shape is located in the shape, otherwise returns false

abstract denormalize_wrt_roi_shape(roi_shape: Rectangle) → ShapeEntity#

The inverse of normalize_wrt_roi_shape.

Transforming shape from the normalized coordinate system to the roi coordinate system. This is used to pull ground truth during training process of the tasks. Examples given in the Shape implementations.

Args:: roi_shape (Rectangle): Shape of the roi.
Returns:: ShapeEntity: Shape in the roi coordinate system.

abstract get_area() → float#: Get the area of the shape.

abstract intersects(other: Shape) → bool#

Returns true if other intersects with shape, otherwise returns false.

Args:: other (Shape): Shape to compare with
Returns:: bool: true if other intersects with shape, otherwise returns false

abstract normalize_wrt_roi_shape(roi_shape: Rectangle) → Shape#

The inverse of denormalize_wrt_roi_shape.

Transforming shape from the roi coordinate system to the normalized coordinate system. This is used when the tasks want to save the analysis results.

For example in Detection -> Segmentation pipeline, the analysis results of segmentation needs to be normalized to the roi (bounding boxes) coming from the detection.

Args:: roi_shape (Rectangle): Shape of the roi.
Returns:: Shape: Shape in the normalized coordinate system.

property type: ShapeType#: Get the type of Shape that this Shape represents.

class otx.api.entities.shapes.shape.ShapeType(value)#

Shows which type of Shape is being used.

ELLIPSE = 1#

POLYGON = 3#

RECTANGLE = 2#