amulet.api.partial_3d_array.unbounded_partial_3d_array module

class amulet.api.partial_3d_array.UnboundedPartial3DArray(dtype, default_value, section_shape, default_section_counts, sections=None)

This is designed to work similarly to a numpy.ndarray but stores the data in a very different way. A numpy.ndarray stores a fixed size continuous array which for large arrays can become unmanageable. Sparse arrays allow individual values to exist which can be great where a small set of values are defined in a large area but get less efficient the denser the defined values are.

This class was born out of the need for an array that has a fixed size in the horizontal directions but an unlimited height in the vertical distance (both above and below the origin) This is achieved by splitting the array into sections of fixed height and storing them sparsely so that only the defined sections need to be held in memory.

This class implements an API that resembles that of a numpy array but it is not directly compatible with numpy. This class also implements methods to access and directly modify the underlying numpy arrays to give finer control.

__init__(dtype, default_value, section_shape, default_section_counts, sections=None)

Construct a UnboundedPartial3DArray. This should not be used directly. You should use the relevant subclass for your use.

Parameters

• dtype (Union[Type[dtype], Type[bool]]) – The dtype that all arrays will be stored in.

• default_value (Union[int, bool]) – The default value that all undefined arrays will be populated with if required.

• section_shape (Tuple[int, int, int]) – The shape of each section array.

• default_section_counts (Tuple[int, int]) – A tuple containing the default number of sections above and below the origin in the y axis. This is used to define the default bounds.

• sections (Optional[Dict[int, ndarray]]) – The sections to initialise the array with.

__repr__()

Return repr(self).

property size_y: float

The size of the array in the y axis. Is always math.inf for the unbounded variant. Read Only

property sections: Iterable[int]

An iterable of the section defined in the array.

create_section(sy)

Create a section array at the given location using the default value and dtype.

Parameters

sy (Union[int, integer]) – The section index to create.

has_section(sy)

Check if the array for a given section exists. :param cy: The section y index :rtype: bool :return: True if the array exists, False otherwise

add_section(sy, section)

Add a section array at the given location.

Parameters

• sy (Union[int, integer]) – The section index to assign the array to.

• section (ndarray) – The array to assign to the section. The shape must equal section_shape.

get_section(sy)

Get the section array for a given section index.

If the section is not defined it will be populated using create_section()

Parameters

sy (Union[int, integer]) – The section index to get.

Return type

ndarray

Returns

Numpy array for this section

__setitem__(slices, value)

Set a sub-section of the infinite height array.

>>> # set the value at a given location
>>> partial_array[3, 4, 5] = 1
>>> # set a cuboid volume in the array
>>> partial_array[2:3, 4:5, 6:7] = 1
>>> # slice and int can be mixed
>>> partial_array[2:3, 4, 6:7] = 1
>>> # if an unbounded slice is given in the y axis it will be capped at the default max and min y values.
>>> partial_array[2:3, :, 6:7] = 1

Parameters

• slices (Tuple[Union[int, integer, slice], Union[int, integer, slice], Union[int, integer, slice]]) – The slices or locations that define the volume to set.

• value (Union[int, integer, ndarray]) – The value to set at the given location. Can be an integer or array.

__getitem__(item)

Get a value or sub-section of the unbounded array.

>>> # get the value at a given location
>>> value = partial_array[3, 4, 5]  # an integer
>>> # get a cuboid volume in the array
>>> value = partial_array[2:3, 4:5, 6:7]  # BoundedPartial3DArray
>>> # slice and int can be mixed
>>> value = partial_array[2:3, 4, 6:7]  # BoundedPartial3DArray
>>> # if an unbounded slice is given in the y axis it will be capped at the default max and min y values.
>>> value = partial_array[2:3, :, 6:7]  # BoundedPartial3DArray

Parameters

item – The slices to extract.

Returns

The value or BoundedPartial3DArray viewing into this array.

__array__(dtype=None)

Get the data contained within as a numpy array.

The y axis will be clamped to the default minimum and maximum y values.

>>> numpy.array(partial_array)

Parameters

dtype – The dtype of the returned numpy array.

Returns

A numpy array of the contained data.

__contains__(item)

Is a section array defined.

>>> 5 in partial_array
True

Parameters

item (int) – The section index to test.

Returns

True if there is an array present for this section. False otherwise

__weakref__

list of weak references to the object (if defined)

property default_value: Union[int, bool]

The default value to populate undefined sections with. Read Only

property dtype: Type[dtype]

The numpy dtype for the arrays. Read Only.

property section_shape: Tuple[int, int, int]

The x, y and z size of a section in the original array.

property shape: Tuple[int, Union[int, float], int]

The size of the array in the x, y and z axis. Read Only

property size_x: int

The size of the array in the x axis. Read Only

property size_z: int

The size of the array in the z axis. Read Only

property slice_x: slice

The slice in the x axis into the original array. Read Only

property slice_y: slice

The slice in the y axis into the original array. Read Only

property slice_z: slice

The slice in the z axis into the original array. Read Only

property slices_tuple: Tuple[Tuple[int, int, int], Tuple[int, int, int], Tuple[int, int, int]]

The slices data in the x, y and z axis into the original array. Read Only

property start: Tuple[int, int, int]

The minimum x, y and z of the slice within the original array. Read Only

property start_x: int

The minimum x value of the slice within the original array. Read Only

property start_y: Optional[int]

The minimum y value of the slice within the original array. Read Only

property start_z: int

The minimum z value of the slice within the original array. Read Only

property step: Tuple[int, int, int]

The step count of the slice in the x, y and z axis. Read Only

property step_x: int

The step count of the slice in the x axis. Read Only

property step_y: int

The step count of the slice in the y axis. Read Only

property step_z: int

The step count of the slice in the z axis. Read Only

property stop: Tuple[int, int, int]

The maximum x value of the slice within the original array. Read Only

property stop_x: int

The maximum x value of the slice within the original array. Read Only

property stop_y: Optional[int]

The maximum y value of the slice within the original array. Read Only

property stop_z: int

The maximum z value of the slice within the original array. Read Only