mapteksdk.data.image_registration module

Raster registration algorithms.

This module contains classes which implement the RasterRegistration interface. This allows them to define how a Raster is displayed on a DataObject subclass.

class RasterRegistrationNone

Bases: RasterRegistration

Class representing no raster registration is present.

Notes

This is always considered valid, so raise_if_valid will never raise an error for this object.

property is_valid: bool

True if the object is valid.

raise_if_invalid()

Checks if the registration is invalid.

Raises a ValueError if the registration is detected to be invalid.

If is_valid is False then calling this function will raise a ValueError containing information on why the registration is considered invalid.

Raises:

ValueError – If the raster is invalid.

copy()

Create a copy of this object.

As of mapteksdk 1.6, a RasterRegistration object can only be associated with one object. Thus a copy is made when attempting to copy registration from one object to another. This function performs this copy.

Returns:

A copy of this object. This copies everything except the link to the associated object, allowing for the copy to be associated with a different object.

Return type:

Self

Raises:

• ValueError – If the registration is invalid.

• RuntimeError – If the registration type doesn’t support being copied.

property raster: Optional[Raster]

The raster which this registration is used by.

The raster returned by the object may be closed. This will be None if this registration is not used by any rasters.

Raises:

ValueError – If set when the registration is already being used by a Raster object.

class RasterRegistrationUnsupported

Bases: RasterRegistration

Class representing a raster registration which is not supported.

If you would like an unsupported registration method to be supported then use request support.

Notes

This is always considered invalid so raise_if_valid will always raise an error.

property is_valid: bool

True if the object is valid.

raise_if_invalid()

Checks if the registration is invalid.

Raises a ValueError if the registration is detected to be invalid.

If is_valid is False then calling this function will raise a ValueError containing information on why the registration is considered invalid.

Raises:

ValueError – If the raster is invalid.

copy()

Create a copy of this object.

As of mapteksdk 1.6, a RasterRegistration object can only be associated with one object. Thus a copy is made when attempting to copy registration from one object to another. This function performs this copy.

Returns:

A copy of this object. This copies everything except the link to the associated object, allowing for the copy to be associated with a different object.

Return type:

Self

Raises:

• ValueError – If the registration is invalid.

• RuntimeError – If the registration type doesn’t support being copied.

property raster: Optional[Raster]

The raster which this registration is used by.

The raster returned by the object may be closed. This will be None if this registration is not used by any rasters.

Raises:

ValueError – If set when the registration is already being used by a Raster object.

class PointPairRegistrationBase

Bases: RasterRegistration

Base class for registration objects which use image/world point pairs.

classmethod minimum_point_pairs()

The minimum number of world / image point pairs required.

Returns:

The minimum number of world / image point pairs required.

Return type:

int

property is_valid: bool

True if the object is valid.

raise_if_invalid()

Checks if the registration is invalid.

Raises a ValueError if the registration is detected to be invalid.

If is_valid is False then calling this function will raise a ValueError containing information on why the registration is considered invalid.

Raises:

ValueError – If the raster is invalid.

property image_points: numpy.ndarray

The points on the image used to map the raster onto an object.

This is a numpy array of points in image coordinates where [0, 0] is the bottom left hand corner of the image and [width - 1, height - 1] is the top right hand corner of the image.

Each of these points should match one of the world points. If the raster is mapped onto an object, the pixel at image_points[i] will be placed at world_points[i] on the surface.

Raises:

• ValueError – If set to a value which cannot be converted to a two dimensional array containing two dimensional points or if any value in the array cannot be converted to a floating point number.

• TypeError – If set to a value which cannot be converted to a numpy array.

property world_points: numpy.ndarray

The world points used to map the raster onto an object.

This is a numpy array of points in world coordinates.

Each of these points should match one of the image points. If the raster is mapped onto an object, the pixel at image_points[i] will be placed at world_points[i] on the surface.

Raises:

• ValueError – If set to a value which cannot be converted to a two dimensional array containing three dimensional points or if any value in the array cannot be converted to a floating point number.

• TypeError – If set to a value which cannot be converted to a numpy array.

copy()

Create a copy of this object.

As of mapteksdk 1.6, a RasterRegistration object can only be associated with one object. Thus a copy is made when attempting to copy registration from one object to another. This function performs this copy.

Returns:

A copy of this object. This copies everything except the link to the associated object, allowing for the copy to be associated with a different object.

Return type:

Self

Raises:

• ValueError – If the registration is invalid.

• RuntimeError – If the registration type doesn’t support being copied.

property raster: Optional[Raster]

The raster which this registration is used by.

The raster returned by the object may be closed. This will be None if this registration is not used by any rasters.

Raises:

ValueError – If set when the registration is already being used by a Raster object.

class RasterRegistrationTwoPoint(image_points=None, world_points=None, orientation=None)

Bases: PointPairRegistrationBase

Represents a simple two-point raster registration.

This simple registration uses two points and an orientation to project a raster onto an object (typically a Surface).

Parameters:

• image_points (Optional[np.ndarray]) – The image points to assign to the object. See the property for more details.

• world_points (Optional[np.ndarray]) – The world points to assign to the object. See the property for more details.

• orientation (Optional[np.ndarray]) – The orientation to assign to the object. See the property for more details.

See also

mapteksdk.data.facets.Surface.associate_raster

Pass a RasterRegistrationTwoPoint and a raster to this function to associate the raster with a surface.

property image_points: numpy.ndarray

The points on the image used to map the raster onto an object.

This is a numpy array of points in image coordinates where [0, 0] is the bottom left hand corner of the image and [width - 1, height - 1] is the top right hand corner of the image.

Each of these points should match one of the world points. If the raster is mapped onto an object, the pixel at image_points[i] will be placed at world_points[i] on the surface.

Raises:

• ValueError – If set to a value which cannot be converted to a two dimensional array containing two dimensional points or if any value in the array cannot be converted to a floating point number.

• TypeError – If set to a value which cannot be converted to a numpy array.

property world_points: numpy.ndarray

The world points used to map the raster onto an object.

This is a numpy array of points in world coordinates.

Each of these points should match one of the image points. If the raster is mapped onto an object, the pixel at image_points[i] will be placed at world_points[i] on the surface.

Raises:

• ValueError – If set to a value which cannot be converted to a two dimensional array containing three dimensional points or if any value in the array cannot be converted to a floating point number.

• TypeError – If set to a value which cannot be converted to a numpy array.

classmethod minimum_point_pairs()

The minimum number of world / image point pairs required.

Returns:

The minimum number of world / image point pairs required.

Return type:

int

property is_valid: bool

True if the object is valid.

raise_if_invalid()

Checks if the registration is invalid.

Raises a ValueError if the registration is detected to be invalid.

If is_valid is False then calling this function will raise a ValueError containing information on why the registration is considered invalid.

Raises:

ValueError – If the raster is invalid.

copy()

Create a copy of this object.

As of mapteksdk 1.6, a RasterRegistration object can only be associated with one object. Thus a copy is made when attempting to copy registration from one object to another. This function performs this copy.

Returns:

A copy of this object. This copies everything except the link to the associated object, allowing for the copy to be associated with a different object.

Return type:

Self

Raises:

• ValueError – If the registration is invalid.

• RuntimeError – If the registration type doesn’t support being copied.

property orientation: numpy.ndarray

The orientation vector used to map the raster onto an object.

This is a numpy array of shape (3,) of the form [X, Y, Z] representing the direction from which the raster is projected onto the object. The components may all be nan for certain raster associations which do not use projections (eg: panoramic image onto a scan).

If this is [0, 0, 1] the raster is projected onto the object from the positive z direction (above). [0, 0, -1] would project the raster onto the object from the negative z direction (below).

Raises:

• ValueError – If set to a value which cannot be converted to a numpy array of shape (3,) or if any value in the array cannot be converted to a floating point number.

• TypeError – If set to a value which cannot be converted to a numpy array.

property raster: Optional[Raster]

The raster which this registration is used by.

The raster returned by the object may be closed. This will be None if this registration is not used by any rasters.

Raises:

ValueError – If set when the registration is already being used by a Raster object.

class RasterRegistrationMultiPoint(image_points=None, world_points=None)

Bases: PointPairRegistrationBase

Represents a multi-point raster registration.

Represents a raster registration which uses eight or more points to project a raster onto an object (typically a Surface).

Parameters:

• image_points (Optional[np.ndarray]) – The image points to assign to the object. See the property for more details.

• world_points (Optional[np.ndarray]) – The world points to assign to the object. See the property for more details.

See also

mapteksdk.data.facets.Surface.associate_raster

Pass a RasterRegistrationMultiPoint and a raster to this function to associate the raster with a surface.

Notes

Though the minimum points required for multi point registration is eight, in most cases twelve or more points are required to get good results.

property image_points: numpy.ndarray

The points on the image used to map the raster onto an object.

This is a numpy array of points in image coordinates where [0, 0] is the bottom left hand corner of the image and [width - 1, height - 1] is the top right hand corner of the image.

Each of these points should match one of the world points. If the raster is mapped onto an object, the pixel at image_points[i] will be placed at world_points[i] on the surface.

Raises:

• ValueError – If set to a value which cannot be converted to a two dimensional array containing two dimensional points or if any value in the array cannot be converted to a floating point number.

• TypeError – If set to a value which cannot be converted to a numpy array.

property world_points: numpy.ndarray

The world points used to map the raster onto an object.

This is a numpy array of points in world coordinates.

Each of these points should match one of the image points. If the raster is mapped onto an object, the pixel at image_points[i] will be placed at world_points[i] on the surface.

Raises:

• ValueError – If set to a value which cannot be converted to a two dimensional array containing three dimensional points or if any value in the array cannot be converted to a floating point number.

• TypeError – If set to a value which cannot be converted to a numpy array.

classmethod minimum_point_pairs()

The minimum number of world / image point pairs required.

Returns:

The minimum number of world / image point pairs required.

Return type:

int

copy()

Create a copy of this object.

As of mapteksdk 1.6, a RasterRegistration object can only be associated with one object. Thus a copy is made when attempting to copy registration from one object to another. This function performs this copy.

Returns:

A copy of this object. This copies everything except the link to the associated object, allowing for the copy to be associated with a different object.

Return type:

Self

Raises:

• ValueError – If the registration is invalid.

• RuntimeError – If the registration type doesn’t support being copied.

property is_valid: bool

True if the object is valid.

raise_if_invalid()

Checks if the registration is invalid.

Raises a ValueError if the registration is detected to be invalid.

If is_valid is False then calling this function will raise a ValueError containing information on why the registration is considered invalid.

Raises:

ValueError – If the raster is invalid.

property raster: Optional[Raster]

The raster which this registration is used by.

The raster returned by the object may be closed. This will be None if this registration is not used by any rasters.

Raises:

ValueError – If set when the registration is already being used by a Raster object.

class RasterRegistrationOverride(image_points)

Bases: RasterRegistration

Provide the world to image point pairs directly.

This is useful when importing data from a source where the registration algorithm has already been applied and the world / image point pairs for the registration are provided in a graphics-card ready form.

Parameters:

image_points (npt.ArrayLike) – The image points to use to register the raster to the surface.

Notes

Unlike the other registration methods provided by the SDK, if this one is used the image points cannot be recalculated when points are added / removed from the Surface. This means if the points or facets of the surface are changed, the raster must be discarded.

Warning

If a raster associated with this registration type is inserted into a container, then attempting to read the raster’s registration will give RasterRegistrationNone.

property image_points: numpy.ndarray

The image points used to register this raster to the surface.

This is an array of shape (point_count, 2). surface.point_to_raster_coordinate_override[i] is the point on the image which corresponds with surface.points[i]. The image point is normalised based on the size of the image. (0.0, 0.0) is the bottom left corner of the raster, and (1.0, 1.0) is the top right corner.

property is_valid: bool

True if the object is valid.

raise_if_invalid()

Checks if the registration is invalid.

Raises a ValueError if the registration is detected to be invalid.

If is_valid is False then calling this function will raise a ValueError containing information on why the registration is considered invalid.

Raises:

ValueError – If the raster is invalid.

copy()

Create a copy of this object.

As of mapteksdk 1.6, a RasterRegistration object can only be associated with one object. Thus a copy is made when attempting to copy registration from one object to another. This function performs this copy.

Returns:

A copy of this object. This copies everything except the link to the associated object, allowing for the copy to be associated with a different object.

Return type:

Self

Raises:

• ValueError – If the registration is invalid.

• RuntimeError – If the registration type doesn’t support being copied.

property raster: Optional[Raster]

The raster which this registration is used by.

The raster returned by the object may be closed. This will be None if this registration is not used by any rasters.

Raises:

ValueError – If set when the registration is already being used by a Raster object.