mapteksdk.common package

Shared helpers and utilities used throughout the API.

trim_pad_2d_array(array_to_check, elements_to_keep=- 1, values=3, fill_value=255)

Converts a list into a 2D np array and ensures it fits within sizing requirements.

The return value is a list with length=elements_to_keep. Each item in this list is a list of length=values.

Parameters

  • array_to_check (array_like) – Array-like object to convert.

  • elements_to_keep (int) – Number of rows expected in the final list. If array_to_check has fewer rows than this number then additional rows will be added to reach this number. If array_to_check has more rows than this number then the extra rows are truncated. The default value is -1, causing no rows to be added or removed.

  • values (int) – Number of columns (values in each row) in the final list. For each row, if it has less than this number of values then it is padded with fill_value. If it has more than this number of values then the row is truncated to this length. The default value is 3.

  • fill_value (any) – Fill value to use when padding. The default is 255.

Returns

A 2D numpy array with elements_to_keep rows and values columns. This contains the values from array_to_check, however with any excess rows/columns truncated or any missing rows/columns padded with fill_value.

Return type

ndarray

Warning

This function has some unintuitive behaviour especially when array_to_check is jagged (rows are not all the same length). Calling it directly is not recommended and it may be deprecated in the future.

Examples

Truncate rows which are too long.

>>> from mapteksdk.common import trim_pad_2d_array
>>> points = [[1, 2, 3, 4], [4, 5, 6, 11], [7, 8, 9, 10]]
>>> trim_pad_2d_array(points, 3, 3)
array([[ 1,  2,  3],
       [ 4,  4,  5],
       [ 6, 11,  7]])

Pad rows which are too short.

>>> from mapteksdk.common import trim_pad_2d_array
>>> points = [[1, 2], [1, 3], [1, 2], [1, 3]]
>>> trim_pad_2d_array(points, -1, 3, 5)
array([[1., 2., 5.],
       [1., 3., 5.],
       [1., 2., 5.],
       [1., 3., 5.]])
trim_pad_1d_array(array_to_check, elements_to_keep=- 1, fill_value=True)

Flattens a 2D array into a 1D array and ensures it fits within sizing requirements. Alternatively, trim or pad a 1D array to have the specified number of elements.

Parameters

  • array_to_check (array_like) – List to trim or pad.

  • elements_to_keep (int) – The length of the final list. If array_to_check is longer than this value, it is truncated to this length. If array_to_check is shorter than this value then it is padded to this length using fill_value. Default is -1 which indicates to keep all elements.

  • fill_value (any) – Fill value to use when padding. Default is True.

Returns

1D numpy array of length elements_to_keep.

Return type

ndarray

See also

trim_pad_2d_array

Similar functionality, but for 2d arrays.

Examples

Enforce list is 1D

>>> from mapteksdk.common import trim_pad_1d_array
>>> visibility = [[True, False, True]]
>>> trim_pad_1d_array(visibility)
array([True, False, True])

Trim a 1D array.

>>> from mapteksdk.common import trim_pad_1d_array
>>> visibility = [True, False, True, True, False]
>>> trim_pad_1d_array(visibility, 3)
array([True, False, True])

Pad a 1D array to the correct length.

>>> from mapteksdk.common import trim_pad_1d_array
>>> visibility = [True]
>>> trim_pad_1d_array(visibility, 3, False)
array([True, False, False])
convert_to_rgba(colour)

Converts a list representing a colour into a valid rgba colour - a list of length 4 in the form [red, green, blue, alpha] with each value between 0 and 255.

This conversion can take three different forms:

  1. If the list contains three elements, the alpha is assumed to be 255 (fully visible).

  2. If the list contains a single element, the colour is treated as a shade of grey.

  3. The colour is already rgba - no conversion is performed.

If none of the above cases are applicable, a ValueError is raised.

Parameters

colour (array_like) – List of colours to convert. This can either be a Greyscale colour ([intensity]), a RGB colour [red, green, blue] or a RGBA colour ([red, green, blue, alpha]).

Returns

ndarray representing colour in the form [red, green, blue, alpha].

Return type

ndarray

Raises

ValueError – If the colour cannot be converted to a valid rgba colour.

Notes

A user of the SDK generally does not need to call this function because it is called internally by all functions which take a colour.

Each element in a rgba array is represented as an unsigned 8 bit integer. If a value is assigned which is greater than 255 or less than 0, integer overflow will occur. The colour will be set to value % 256.

Alpha represents the transparency of the object - an alpha of 0 indicates a completely transparent (and hence invisible) colour whereas an alpha of 255 indicates a completely opaque object.

Examples

Convert greyscale colour to RGBA

>>> from mapteksdk.common import convert_to_rgba
>>> colour = [125]
>>> convert_to_rgba(colour)
array([125, 125, 125, 255])

Convert RGB colour to RGBA

>>> from mapteksdk.common import convert_to_rgba
>>> colour = [120, 120, 0]
>>> convert_to_rgba(colour)
array([120, 120, 0, 255])
convert_array_to_rgba(colour_array, expected_size, default_colour=None)

Converts a list of colours to a valid ndarray of RGBA colours containing expected_size colours. The conversions uses the same rules as convert_to_rgba.

Parameters

  • colour_array (array_like) – List of lists representing colours to convert to RGBA.

  • expected_size (int) – Number of elements required in the final array. If colour_array is too long it is truncated to the correct length. If colour_array is too short it is padded with default_colour to the correct length.

  • default_colour (array_like) – List representing the colour to append when padding the colour array. Default is Green ([0, 255, 0, 255]).

Returns

Input list trimmed or padded to the correct length with each element converted to RGBA ([red, green, blue, alpha]).

Return type

ndarray

Raises

  • ValueError – If colour_array is jagged - Not all colours in the array are in the same format, for example if some colours are represented as RGB and others are represented as RGBA.

  • ValueError – If colour array contains colours which are not represented in greyscale, RGB or RGBA format.

  • ValueError – If default colour is not valid.

Examples

Convert list of RGB colours to RGBA.

>>> from mapteksdk.common import convert_array_to_rgba
>>> colours = [[125, 125, 125], [120, 120, 0]]
>>> convert_array_to_rgba(colours, 3)
array([[125, 125, 125, 255],
       [120, 120,   0, 255],
       [  0, 255,   0, 255]], dtype=uint8)