Region module
This module contains classes for region representation and manipulation.
Regions are also used to represent results of trackers as well as groundtruth trajectories. The module also contains functions for calculating overlaps between regions and for converting between different region types.
- exception vot.region.ConversionException(*args, source=None)
Region conversion exception, the conversion cannot be performed.
- class vot.region.Point(x, y)
Special region, meaning of the code can change depending on the context.
- Variables
code – Code value
- static convert(region: Region)
Convert region to point region. Note that some conversions degrade information.
- Parameters
region (Region) – Region to convert
- Raises
ConversionException – Unable to convert region to point region
- Returns
Point – Converted region
- copy()
Copy region to another object.
- draw(handle: DrawHandle)
Draw region to the image using the provided handle.
- Parameters
handle (DrawHandle) – Draw handle
- is_empty()
Check if region is empty.
Point regions are never empty by definition.
- resize(scale)
Resize region by the provided scale factor.
- Parameters
scale (float) – Scale factor
- property x
Retiurns X coordinate of the point.
- Returns
float – X coordinate
- property y
Retiurns Y coordinate of the point.
- Returns
float – Y coordinate
- class vot.region.Region
Base class for all region containers.
- abstract copy()
Copy region to another object.
- Returns
Region – Copy of the region
- exception vot.region.RegionException
General region exception.
- class vot.region.Special(code)
Special region, meaning of the code can change depending on the context.
- Variables
code – Code value
- property code
Retiurns special code for this region.
- Returns
int – Type code
- static convert(region: Region)
Convert region to special region. Note that some conversions degrade information.
- Parameters
region (Region) – Region to convert
- Raises
ConversionException – Unable to convert region to special region
- Returns
Special – Converted region
- copy()
Create a copy of the special region.
- draw(handle: DrawHandle)
Draw region to the image using the provided handle.
- Parameters
handle (DrawHandle) – Draw handle
- is_empty()
Check if region is empty.
Special regions are always empty by definition.
- vot.region.is_shape(region)
Check if the region is a shape region.
- Parameters
region (Region) – Region to check
- Returns
True if the region is a shape region, False otherwise
- Return type
bool
- vot.region.is_special(region)
Check if the region is a special region.
- Parameters
region (Region) – Region to check
- Returns
True if the region is a special region, False otherwise
- Return type
bool
Shapes
Module for region shapes.
- class vot.region.shapes.Mask(mask: array, offset: Tuple[int, int] = (0, 0), optimize=False)
Mask region defined by a binary mask.
The mask is defined by a binary image and an offset.
- bounds()
Get the bounding box of the mask.
- Returns
Bounding box of the mask as (left, top, right, bottom).
- Return type
tuple
- static convert(region: Region)
Convert region to mask region. Note that some conversions degrade information.
- Parameters
region (Region) – Region to convert
- Raises
ConversionException – Unable to convert region to mask region
- Returns
Mask – Converted region
- copy()
Create a copy of the mask.
- draw(handle: DrawHandle)
Draw the mask into an image.
- Parameters
handle (DrawHandle) – Handle to the image.
- is_empty()
Check if the mask is empty.
- Returns
True if the mask is empty, False otherwise.
- Return type
bool
- property mask
Get the mask.
Note that you should not modify the mask directly. Also make sure to take into account the offset when using the mask.
- move(dx=0, dy=0)
Move the mask by a given offset.
- Parameters
dx (int) – Horizontal offset.
dy (int) – Vertical offset.
- Returns
Moved mask.
- Return type
- property offset
Get the offset of the mask in pixels.
- rasterize(bounds: Tuple[int, int, int, int])
Rasterize the mask into a binary mask. The mask is cropped to the given bounds.
- Parameters
bounds (tuple) – Bounding box of the mask as (left, top, right, bottom).
- Returns
Binary mask. The mask is a copy of the original mask.
- Return type
numpy.ndarray
- class vot.region.shapes.Polygon(points)
Polygon region defined by a list of points.
The polygon is closed, i.e. the first and last point are connected.
- bounds()
Get the bounding box of the polygon.
- Returns
Bounding box as (left, top, right, bottom).
- Return type
tuple
- static convert(region: Region)
Convert region to polygon region. Note that some conversions degrade information.
- Parameters
region (Region) – Region to convert
- Raises
ConversionException – Unable to convert region to polygon region
- Returns
Polygon – Converted region
- copy()
Create a copy of the polygon.
- draw(handle: DrawHandle)
Draw the polygon on the given handle.
- Parameters
handle (DrawHandle) – Handle to draw on.
- is_empty()
Check if the polygon is empty.
- Returns
True if the polygon is empty, False otherwise.
- Return type
bool
- move(dx=0, dy=0)
Move the polygon by a given offset.
- Parameters
dx (float) – X offset.
dy (float) – Y offset.
- Returns
Moved polygon.
- Return type
- points()
Get the list of points.
- Returns
List of points as tuples [(x1,y1), (x2,y2),…,(xN,yN)]
- Return type
list
- rasterize(bounds: Tuple[int, int, int, int])
Rasterize the polygon into a binary mask.
- Parameters
bounds (tuple) – Bounding box of the mask as (left, top, right, bottom).
- Returns
Binary mask.
- Return type
numpy.ndarray
- resize(factor=1)
Resize the polygon by a factor.
- Parameters
factor (float) – Resize factor.
- Returns
Resized polygon.
- Return type
- property size
Get the number of points.
- class vot.region.shapes.Rectangle(x=0, y=0, width=0, height=0)
Rectangle region class for representing rectangular regions.
- bounds()
Get the bounding box of the region.
- Returns
Bounding box (x1,y1,x2,y2).
- Return type
tuple
- center()
Get the center of the region.
- Returns
Center coordinates (x,y).
- Return type
tuple
- static convert(region: Region)
Convert region to rectangle region. Note that some conversions degrade information.
- Parameters
region (Region) – Region to convert
- Raises
ConversionException – Unable to convert region to rectangle region
- Returns
Rectangle – Converted region
- copy()
Copy region to another object.
- draw(handle: DrawHandle)
Draw the region to the given handle.
- Parameters
handle (DrawHandle) – Handle to draw to.
- property height
Height of the rectangle.
- is_empty()
Check if the region is empty.
- Returns
True if the region is empty, False otherwise.
- Return type
bool
- move(dx=0, dy=0)
Move the region by the given offset.
- Parameters
dx (float, optional) – X offset. Defaults to 0.
dy (float, optional) – Y offset. Defaults to 0.
- Returns
Moved region.
- Return type
- rasterize(bounds: Tuple[int, int, int, int])
Rasterize the region to a binary mask.
- Parameters
bounds (tuple) – Bounds of the mask (x1,y1,x2,y2).
- resize(factor=1)
Resize the region by the given factor.
- Parameters
factor (float, optional) – Resize factor. Defaults to 1.
- Returns
Resized region.
- Return type
- property width
Width of the rectangle.
- property x
X coordinate of the top left corner.
- property y
Y coordinate of the top left corner.
- class vot.region.shapes.Shape
Base class for all shape regions.
- abstract bounds() Tuple[int, int, int, int]
Get the bounding box of the region.
- Returns
Bounding box (x, y, width, height).
- Return type
Tuple[int, int, int, int]
- abstract draw(handle: DrawHandle) None
Draw the region to the given handle.
- abstract move(dx=0, dy=0) Shape
Move the region by the given offset.
- Parameters
dx (float, optional) – X offset. Defaults to 0.
dy (float, optional) – Y offset. Defaults to 0.
- Returns
Moved region.
- Return type
- abstract rasterize(bounds: Tuple[int, int, int, int]) ndarray
Rasterize the region to a binary mask.
- Parameters
bounds (Tuple[int, int, int, int]) – Bounds of the mask.
- Returns
Binary mask.
- Return type
np.ndarray
Raster utilities
Rasterization of regions.
This module contains functions for rasterizing different region types.
- vot.region.raster.calculate_overlap(reg1: Shape, reg2: Shape, bounds: Optional[Tuple[int, int]] = None, ignore: Optional[Shape] = None)
Calculate the overlap between two regions. The function first rasterizes both regions to 2-D binary masks and calculates overlap between them.
- Parameters
reg1 – first region
reg2 – second region
bounds – 2-tuple with the bounds of the image (width, height)
ignore – region to ignore when calculating overlap, usually a mask
- Returns
float with the overlap between the two regions. Note that overlap is one by definition if both regions are empty.
- vot.region.raster.calculate_overlaps(first: List[Region], second: List[Region], bounds: Optional[Tuple[int, int]] = None, ignore: Optional[List[Region]] = None)
Calculate the overlap between two lists of regions. The function first rasterizes both regions to 2-D binary masks and calculates overlap between them.
- Parameters
first – first list of regions
second – second list of regions
bounds – 2-tuple with the bounds of the image (width, height)
ignore – list of regions to ignore when calculating overlap, usually a list of masks
- Returns
list of floats with the overlap between the two regions. Note that overlap is one by definition if both regions are empty.
- Raises
RegionException – if the lists are not of the same size
- vot.region.raster.copy_mask(mask: ndarray, offset: Tuple[int, int], bounds: Tuple[int, int, int, int])
Copy a mask to a new location. This is a Numba implementation of the function that is compiled to machine code for faster execution.
- Parameters
mask – 2-D array with the mask
offset – 2-tuple with the offset of the mask
bounds – 4-tuple with the bounds of the image (left, top, right, bottom)
- Returns
2-D array with the copied mask
- vot.region.raster.mask_bounds(mask: ndarray)
Compute bounds of a binary mask. Bounds are defined as the minimal axis-aligned region containing all positive pixels. This is a Numba implementation of the function that is compiled to machine code for faster execution.
- Parameters
mask (np.ndarray) – 2-D array with a binary mask
- Returns
coordinates of the top-left and bottom-right corners of the minimal axis-aligned region containing all positive pixels
- vot.region.raster.rasterize_polygon(data: ndarray, bounds: Tuple[int, int, int, int])
Rasterize a polygon. This is a Numba implementation of the function that is compiled to machine code for faster execution.
- Parameters
data – Nx2 array with polygon coordinates
bounds – 4-tuple with the bounds of the image (left, top, right, bottom)
- Returns
2-D array with the rasterized polygon
- vot.region.raster.rasterize_rectangle(data: ndarray, bounds: Tuple[int, int, int, int])
Rasterize a rectangle. This is a Numba implementation of the function that is compiled to machine code for faster execution.
- Parameters
data – 4x1 array with rectangle coordinates (x, y, width, height)
bounds – 4-tuple with the bounds of the image (left, top, right, bottom)
- Returns
2-D array with the rasterized rectangle
IO functions
Utilities for reading and writing regions from and to files.
- vot.region.io.create_mask_from_string(mask_encoding)
mask_encoding: a string in the following format: x0, y0, w, h, RLE output: mask, offset mask: 2-D binary mask, size defined in the mask encoding offset: (x, y) offset of the mask in the image coordinates
- vot.region.io.encode_mask(mask)
Encode a binary mask to a string in the following format: x0, y0, w, h, RLE.
- Parameters
mask (np.ndarray) – 2-D binary mask
- Returns
Encoded mask
- Return type
str
- vot.region.io.mask_to_rle(m, maxstride=100000000)
Converts a binary mask to RLE encoding. This is a Numba decorated function that is compiled just-in-time for faster execution.
- Parameters
m (np.ndarray) – 2-D binary mask
maxstride (int) – Maximum number of consecutive 0s or 1s in the RLE encoding. If the number of consecutive 0s or 1s is larger than maxstride, it is split into multiple elements.
- Returns
RLE encoding of the mask
- Return type
List[int]
- vot.region.io.parse_region(string: str, separator: str = ',') Region
Parse input string to the appropriate region format and return Region object.
- Parameters
string (str) – comma separated list of values
separator (str) – separator of values in the input string
- Returns
resulting region
- Return type
- vot.region.io.read_trajectory(fp: Union[str, TextIO], separator: str = ',')
Reads a trajectory from a file and returns a list of regions.
- Parameters
fp (str or TextIO) – File path or file pointer to the trajectory file
separator (str) – Separator of values in the region, only used for text files
- Returns
List of regions
- Return type
list
- vot.region.io.read_trajectory_binary(fp: RawIOBase)
Reads a trajectory from a binary file and returns a list of regions.
- Parameters
fp (io.RawIOBase) – File pointer to the binary file
- Returns
List of regions
- Return type
list
- vot.region.io.rle_to_mask(rle, width, height)
Converts RLE encoding to a binary mask. This is a Numba decorated function that is compiled just-in-time for faster execution.
- Parameters
rle (List[int]) – RLE encoding of the mask
width (int) – Width of the mask
height (int) – Height of the mask
- Returns
2-D binary mask
- Return type
np.ndarray
- vot.region.io.write_trajectory(fp: Union[str, TextIO], data: List[Region])
Write a trajectory to a file handle or a file with a given name. Based on the suffix of a file or properties of a file handle, the output may be either text based or binary.
- Parameters
fp (Union[str, TextIO]) – File handle or file name
data (List[Region]) – Trajectory, a list of region objects
- Raises
IOError – If the file format is not supported