mapteksdk.data.images module¶

Module containing classes for interacting with raster objects.

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

Bases: mapteksdk.data.base.DataObject

Class representing raster images which can be draped onto other objects. This class is only useful for editing an existing raster. Though it is possible to create a new raster, this class does not provide any methods for associating the image with an existing 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.

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

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