mapteksdk.data.images module¶

Module containing classes for interacting with raster objects.

class mapteksdk.data.images.Raster(object_id=None, lock_type=LockType.READWRITE, width=1, height=1)¶

Bases: mapteksdk.data.base.DataObject

Class representing raster images which can be draped onto other objects. Topology objects which support raster association possess an associate_raster function which accepts a Raster and a RasterRegistration object which allows the raster to be draped onto that object.

Notes

This object provides a consistent interface to the pixels of the raster image regardless of the underlying format. If the underlying format is JPEG or another format which does not support alpha, the alpha will always be read as 255 and any changes to the alpha components will be ignored.

See also

mapteksdk.data.facets.Surface.associate_raster: associate a raster with a surface.

classmethod static_type()¶

Return the type of raster as stored in a Project.

This can be used for determining if the type of an object is a raster.

property width¶: The width of the raster. This is the number of pixels in each row.

property height¶: The height of the raster. This is the number of pixels in each column.

resize(new_width, new_height, resize_image=True)¶

Resizes the raster to the new width and height.

Parameters

new_width (int) – The new width for the raster. Pass None to keep the width unchanged.
new_height (int) – The new height for the raster. Pass None to keep the height unchanged.
resize_image (bool) – If True (default) The raster will be resized to fill the new size using a simple nearest neighbour search if the size is reduced, or simple bilinear interpolation. This will also change the format to JPEG (and hence the alpha component of the pixels will be discarded). If False, the current pixels are discarded and replaced with transparent white (or white if the format does not support transparency). This will not change the underlying format.

Raises

TypeError – If width or height cannot be converted to an integer.
ValueError – If width or height is less than one.
RuntimeError – If called when creating a new raster.

Warning

After calling resize with resize_image=True it is an error to access pixels or pixels_2d until the object is closed and reopened.

Examples

Halve the size of all rasters on an object. Note that because resize_image is true, the existing pixels will be changed to make a smaller version of the image.

>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.read("surfaces/target") as read_object:
>>>     for raster in read_object.rasters.values():
...         with project.edit(raster) as edit_raster:
...             edit_raster.resize(edit_raster.width // 2,
...                                edit_raster.height // 2,
...                                resize_image=True)

property pixel_count¶: The total number of pixels in the raster.

property pixels¶

The pixels of the raster object represented as a numpy array of shape (pixel_count, 4) where each row is the colour of a pixel in the form: [Red, Green, Blue, Alpha].

See pixels_2d for the pixels reshaped to match the width and height of the raster.

Raises: RuntimeError – If accessed after calling resize with resize_image = True.

Notes

The default colour is transparent white. This may appear as white if the raster is stored in a format which does not support alpha.

Examples

Accessing the pixels via this function is best when the two dimensional nature of the raster is not relevant or useful. The below example shows removing the green component from all of the pixels in an raster. Has no effect if the object at surfaces/target does not have an associated raster.

>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.read("surfaces/target") as read_object:
>>>     for raster in read_object.rasters.values():
...         with project.edit(raster) as edit_raster:
...             edit_raster.pixels[:, 1] = 0

property pixels_2d¶

The pixels reshaped to match the width and height of the raster. pixels_2d[0][0] is the colour of the pixel in the bottom left hand corner of the raster. pixels_2d[i][j] is the colour of the pixel i pixels to the right of the bottom left hand corner and j pixels above the bottom left hand corner.

The returned array will have shape (height, width, 4).

Notes

This returns the pixels in an ideal format to be passed to the raster.fromarray function in the 3rd party pillow library.

Examples

As pixels_2d allows access to the two dimensional nature of the raster, it can allow different transformations to be applied to different parts of the raster. The example below performs a different transformation to each quarter of the raster. Has no effect if the object at surfaces/target has no associated rasters.

>>> from mapteksdk.project import Project
>>> project = Project()
>>> with project.read("surfaces/target") as read_object:
...     for raster in read_object.rasters.values():
...         with project.edit(raster) as edit_raster:
...             width = edit_raster.width
...             height = edit_raster.height
...             half_width = edit_raster.width // 2
...             half_height = edit_raster.height // 2
...             # Remove red from the bottom left hand corner.
...             edit_raster.pixels_2d[0:half_height, 0:half_width, 0] = 0
...             # Remove green from the top left hand corner.
...             edit_raster.pixels_2d[half_height:height,
...                                   0:half_width, 1] = 0
...             # Remove blue from the bottom right hand corner.
...             edit_raster.pixels_2d[0:half_height,
...                                   half_width:width, 2] = 0
...             # Maximizes the red component in the top right hand corner.
...             edit_raster.pixels_2d[half_height:height,
...                                   half_width:width, 0] = 255

property title¶

The title of the raster.

This is shown in the manage images panel. Generally this is the name of the file the raster was imported from.

property registration¶

Returns the registration object which defines how the raster is draped onto Topology Objects.

If no raster registration is set this will return a RasterRegistrationNone object. If raster registration is set but the SDK does not support the type of registration it will return a RasterRegistrationUnsupported object. Otherwise it will return a RasterRegistration subclass representing the existing registration.

Raises

TypeError – If set to a value which is not a RasterRegistration.
ValueError – If set to an invalid RasterRegistration.

Notes

You should not assign to this property directly. Instead pass the registration to the associate_raster() function of the object you would like to associate the raster with.

save()¶: Saves changes to the raster to the Project.

class mapteksdk.data.images.RasterRegistration¶

Bases: object

Base class for all types of raster registration. This is useful for type checking.

property is_valid¶: True if the object is valid.

raise_if_invalid()¶

Checks if the raster is invalid and raises a ValueError if any invalid information is detected.

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.

class mapteksdk.data.images.RasterRegistrationNone¶

Bases: mapteksdk.data.images.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¶: True if the object is valid.

raise_if_invalid()¶

Checks if the raster is invalid and raises a ValueError if any invalid information is detected.

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.

class mapteksdk.data.images.RasterRegistrationUnsupported¶

Bases: mapteksdk.data.images.RasterRegistration

Class representing a raster registration which is not supported by the SDK.

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¶: True if the object is valid.

raise_if_invalid()¶

Checks if the raster is invalid and raises a ValueError if any invalid information is detected.

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.

class mapteksdk.data.images.PointPairRegistrationBase¶

Bases: mapteksdk.data.images.RasterRegistration

Base class for registration objects which use image/world point pairs to register the image to a Surface.

classmethod minimum_point_pairs()¶

The minimum number of world / image point pairs required for this type of registration.

Returns: The minimum number of world / image point pairs required.
Return type: int

property is_valid¶: True if the object is valid.

raise_if_invalid()¶

Checks if the raster is invalid and raises a ValueError if any invalid information is detected.

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¶

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, height] 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¶

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.

class mapteksdk.data.images.RasterRegistrationTwoPoint(image_points=None, world_points=None, orientation=None)¶

Bases: mapteksdk.data.images.PointPairRegistrationBase

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

Parameters

image_points (numpy.ndarray) – The image points to assign to the object. See the property for more details.
world_points (numpy.ndarray) – The world points to assign to the object. See the property for more details.
orientation (numpy.ndarray) – The orientation to assign to the object. See the property for more details.