amulet.api.selection.group module

class amulet.api.selection.SelectionGroup(selection_boxes=())

Bases: AbstractBaseSelection

A container for zero or more SelectionBox instances.

This allows for non-rectangular and non-contiguous selections.

__init__(selection_boxes=())

Construct a new SelectionGroup class from the given data.

>>> SelectionGroup(SelectionBox((0, 0, 0), (1, 1, 1)))
>>> SelectionGroup([
>>>     SelectionBox((0, 0, 0), (1, 1, 1)),
>>>     SelectionBox((1, 1, 1), (2, 2, 2))
>>> ])

Parameters

selection_boxes (Union[SelectionBox, Iterable[SelectionBox]]) – A SelectionBox or iterable of SelectionBox classes.

contains_block(coords)

Is the block contained within the selection.

>>> (1, 2, 3) in selection1
True

Parameters

coords (Union[Tuple[int, int, int], ndarray, Tuple[float, float, float]]) – The coordinate of the block defined by the most negative corner.

Return type

bool

Returns

True if the block is in the selection.

contains_point(coords)

Is the point contained within the selection.

>>> (1.5, 2.5, 3.5) in selection1
True

Parameters

coords (Union[Tuple[int, int, int], ndarray, Tuple[float, float, float]]) – The coordinate of the point.

Return type

bool

Returns

True if the point is in the selection.

property blocks: Iterable[Tuple[int, int, int]]

The location of every block in the selection.

>>> for x, y, z in group.blocks:
>>>     ...

Note: if boxes intersect, the blocks in the intersected region will be included multiple times.

If this behaviour is not desired the merge_boxes() method will return a new SelectionGroup with no intersections.

>>> for x, y, z in group.merge_boxes().blocks:
>>>     ...

Returns

An iterable of block locations.

property min: Tuple[int, int, int]

The minimum point of of all the boxes in the group.

property min_array: ndarray

The minimum point of of all the boxes in the group as a numpy array.

property min_x: int

The minimum x coordinate of the selection.

property min_y: int

The minimum y coordinate of the selection.

property min_z: int

The minimum z coordinate of the selection.

property max: Tuple[int, int, int]

The maximum point of of all the boxes in the group.

property max_array: ndarray

The maximum point of of all the boxes in the group as a numpy array.

property max_x: int

The maximum x coordinate of the selection.

property max_y: int

The maximum y coordinate of the selection.

property max_z: int

The maximum z coordinate of the selection.

property bounds: Tuple[Tuple[int, int, int], Tuple[int, int, int]]

The minimum and maximum points in the selection.

property bounds_array: ndarray

The minimum and maximum points in the selection as a numpy array.

to_box()

Create a SelectionBox based off the bounds of the boxes in the group.

Return type

SelectionBox

merge_boxes()

Take the boxes as they were given to this class, merge neighbouring boxes and remove overlapping regions.

The result should be a SelectionGroup containing one or more SelectionBox classes that represents the same volume as the original but with no overlapping boxes.

Return type

SelectionGroup

property is_contiguous: bool

Does the SelectionGroup represent one connected region (True) or multiple separated regions (False).

If two boxes are touching at the corners this is classed as contiguous.

property is_rectangular: bool

Checks if the SelectionGroup is a rectangle

Returns

True is the selection is a rectangle, False otherwise

property selection_boxes: Tuple[SelectionBox, ...]

A tuple of the SelectionBox instances stored for this group.

property selection_boxes_sorted: List[SelectionBox]

A list of the SelectionBox instances for this group sorted by their hash.

chunk_count(sub_chunk_size=16)

The number of chunks that intersect the selection.

Parameters

sub_chunk_size (int) – The dimension of a sub-chunk. Default 16.

Return type

int

chunk_locations(sub_chunk_size=16)

An iterable of chunk coordinates that intersect the selection.

>>> for cx, cz in selection1.chunk_locations():
>>>     ...

Parameters

sub_chunk_size (int) – The dimension of a sub-chunk. Default 16.

Return type

Set[Tuple[int, int]]

chunk_boxes(sub_chunk_size=16)

An iterable of chunk coordinates and boxes that intersect the selection and the chunk.

>>> for (cx, cz), box in selection1.chunk_boxes():
>>>     ...

Parameters

sub_chunk_size (int) – The dimension of a sub-chunk. Default 16.

Return type

Iterable[Tuple[Tuple[int, int], SelectionBox]]

sub_chunk_count(sub_chunk_size=16)

The number of sub-chunks that intersect the selection.

Parameters

sub_chunk_size (int) – The dimension of a sub-chunk. Default 16.

Return type

int

sub_chunk_locations(sub_chunk_size=16)

An iterable of sub-chunk coordinates that intersect the selection.

>>> for cx, cy, cz in selection1.sub_chunk_locations():
>>>     ...

Parameters

sub_chunk_size (int) – The dimension of a sub-chunk. Default 16.

Return type

Set[Tuple[int, int, int]]

sub_chunk_boxes(sub_chunk_size=16)

An iterable of sub-chunk coordinates and boxes that intersect the selection and the sub-chunk.

>>> for (cx, cy, cz), box in selection1.sub_chunk_boxes():
>>>     ...

Parameters

sub_chunk_size (int) – The dimension of a sub-chunk. Default 16.

Return type

Iterable[Tuple[Tuple[int, int, int], SelectionBox]]

intersects(other)

Does this selection intersect other.

Parameters

other (Union[SelectionGroup, SelectionBox]) – The other selection.

Return type

bool

Returns

True if the selections intersect, False otherwise.

intersection(other)

Create and return a new a selection containing the volume that this selection and other both contain.

If the selections do not intersect the returned selection will have no volume.

Use intersects() to test if the two selections intersect.

Parameters

other (Union[SelectionGroup, SelectionBox]) – The other selection.

Return type

SelectionGroup

Returns

A new selection containing the intersection.

subtract(other)

Returns a new SelectionGroup containing the volume that does not intersect with other.

This may be empty if other fully contains self or equal to self if they do not intersect.

Parameters

other (Union[SelectionGroup, SelectionBox]) – The SelectionBox or SelectionGroup to subtract.

Return type

SelectionGroup

union(other)

Returns a new SelectionGroup containing the volume of self and other.

Parameters

other (Union[SelectionGroup, SelectionBox]) – The other selection to add to this one.

Return type

SelectionGroup

is_subset(other)

Is this selection completely contained within other.

Parameters

other (Union[SelectionGroup, SelectionBox]) – The other selection to test against.

Return type

bool

Returns

True if this selection completely fits in other.

closest_vector_intersection(origin, vector)

Returns the index for the closest box in the look vector and the multiplier of the look vector to get there.

Parameters

• origin (Union[Tuple[float, float, float], ndarray]) – The origin tuple of the vector

• vector (Union[Tuple[float, float, float], ndarray]) – The vector magnitude in x, y and z

Return type

Tuple[Optional[int], float]

Returns

Index for the closest box and the multiplier of the vector to get there. None, inf if no intersection.

transform(scale, rotation, translation)

Creates a new SelectionGroup transformed by the given inputs.

Parameters

• scale (Tuple[float, float, float]) – A tuple of scaling factors in the x, y and z axis.

• rotation (Tuple[float, float, float]) – The rotation about the x, y and z axis in radians.

• translation (Tuple[float, float, float]) – The translation about the x, y and z axis.

Return type

SelectionGroup

Returns

A new SelectionGroup representing the transformed selection.

property volume: int

The number of blocks in the selection.

property footprint_area: int

The 2D area that the selection fills when looking at the selection from above.