Shifted Cartesian Layout¶

Coordinate system that represents a shifted Cartesian grid of signed coordinates. The faces of a shifted Cartesian layout are arranged by shifting either odd or even rows (horizontal shift) or columns (vertical shift) inwards. The arrangement is a value that the layout receives at construction. The layout shares its members with hexagonal_layout, and Hexagonal Layout documents the arrangement type.

C++

Header: fiction/layouts/shifted_cartesian_layout.hpp

class shifted_cartesian_layout : public fiction::layouts::hexagonal_layout ¶

A layout type that utilizes offset coordinates to represent a Cartesian layout with shifted coordinates. Its faces are organized in an offset coordinate system as provided. The arrangement fixed at construction selects which rows or columns are shifted. Row arrangements shift horizontally, column arrangements vertically. The four arrangements look as follows.

arrangement::ODD_ROW:

+-------+-------+-------+
|       |       |       |
| (0,0) | (1,0) | (2,0) |
|       |       |       |
+---+---+---+---+---+---+---+
    |       |       |       |
    | (0,1) | (1,1) | (2,1) |
    |       |       |       |
+---+---+---+---+---+---+---+
|       |       |       |
| (0,2) | (1,2) | (2,2) |
|       |       |       |
+-------+-------+-------+

arrangement::EVEN_ROW:

    +-------+-------+-------+
    |       |       |       |
    | (0,0) | (1,0) | (2,0) |
    |       |       |       |
+---+---+---+---+---+---+---+
|       |       |       |
| (0,1) | (1,1) | (2,1) |
|       |       |       |
+---+---+---+---+---+---+---+
    |       |       |       |
    | (0,2) | (1,2) | (2,2) |
    |       |       |       |
    +-------+-------+-------+

arrangement::ODD_COLUMN:

 +-------+       +-------+
 |       |       |       |
 | (0,0) +-------+ (2,0) +-------+
 |       |       |       |       |
 +-------+ (1,0) +-------+ (3,0) |
 |       |       |       |       |
 | (0,1) +-------+ (2,1) +-------+
 |       |       |       |       |
 +-------+ (1,1) +-------+ (3,1) |
 |       |       |       |       |
 | (0,2) +-------+ (2,2) +-------+
 |       |       |       |
 +-------+       +-------+

arrangement::EVEN_COLUMN:

        +-------+       +-------+
        |       |       |       |
+-------+ (1,0) +-------+ (3,0) |
|       |       |       |       |
| (0,0) +-------+ (2,0) +-------+
|       |       |       |       |
+-------+ (1,1) +-------+ (3,1) |
|       |       |       |       |
| (0,1) +-------+ (2,1) +-------+
|       |       |       |       |
+-------+ (1,2) +-------+ (3,2) |
        |       |       |       |
        +-------+       +-------+

Subclassed by fiction::layouts::gate_level_layout< layouts::shifted_cartesian_layout >

Public Types

using is_shifted_cartesian = std::true_type¶: Marks the layout as shifted Cartesian, which distinguishes it from the hexagonal layout it shares its neighbor geometry with.

Public Functions

inline explicit shifted_cartesian_layout(const arrangement a, const HexagonalLayout::extent &size = {})¶

Creates geometry with half-open, zero-origin bounds. The default extent is empty.

Parameters:

a – Arrangement of shifted rows or columns.
size – Axis sizes.

Throws:

std::invalid_argument – If a size exceeds the coordinate domain.
std::out_of_range – If the layer count exceeds two.

inline shifted_cartesian_layout(const HexagonalLayout &lyt) noexcept¶

Parameters:: lyt – Hexagonal geometry to copy.

Python

class shifted_cartesian_layout(arrangement: arrangement)¶

class shifted_cartesian_layout(arrangement: arrangement, extent: extent | tuple[int, int] | tuple[int, int, int])

A layout type that utilizes offset coordinates to represent a Cartesian layout with shifted rows or columns selected by its arrangement. This example uses arrangement.ODD_COLUMN:

        +-------+       +-------+
        |       |       |       |
+-------+ (1,0) +-------+ (3,0) |
|       |       |       |       |
| (0,0) +-------+ (2,0) +-------+
|       |       |       |       |
+-------+ (1,1) +-------+ (3,1) |
|       |       |       |       |
| (0,1) +-------+ (2,1) +-------+
|       |       |       |       |
+-------+ (1,2) +-------+ (3,2) |
        |       |       |       |
        +-------+       +-------+

above(c: coordinate | tuple[int, int] | tuple[int, int, int]) → coordinate | None¶

Returns the above neighbor when both coordinates lie inside the geometry.

Parameters:: c – Base coordinate.
Returns:: Neighbor, or no value at a boundary or outside the geometry.

adjacent_coordinates(c: coordinate | tuple[int, int] | tuple[int, int, int]) → list[coordinate]¶

Returns a container that contains all coordinates that are adjacent to a given one. Thereby, only cardinal directions are being considered, i.e., the container contains all coordinates ac for which is_adjacent(c, ac) returns true.

Coordinates that are outside of the layout bounds are not considered. Thereby, the size of the returned container is at most 4.

Parameters:: c – Coordinate whose adjacent ones are desired.
Returns:: A container that contains all of c’s adjacent coordinates.

adjacent_opposite_coordinates(c: coordinate | tuple[int, int] | tuple[int, int, int]) → list[tuple[coordinate, coordinate]]¶

Returns a container that contains all coordinates pairs of opposing adjacent coordinates with respect to a given one. In this Cartesian layout, the container will contain (north(c), south(c)) and (east(c), west(c)).

This function comes in handy when straight lines on the layout are to be examined.

Coordinates outside of the layout bounds are not being considered.

Parameters:: c – Coordinate whose opposite ones are desired.
Returns:: A container that contains pairs of c’s opposing coordinates.

area() → int¶

Returns:: Width times height.

below(c: coordinate | tuple[int, int] | tuple[int, int, int]) → coordinate | None¶

Returns the below neighbor when both coordinates lie inside the geometry.

Parameters:: c – Base coordinate.
Returns:: Neighbor, or no value at a boundary or outside the geometry.

contains_coordinate(c: coordinate | tuple[int, int] | tuple[int, int, int]) → bool¶: Tests the half-open geometry bounds.

coord(x: int, y: int, z: int = 0) → coordinate¶

Creates and returns a coordinate in the layout from the given x-, y-, and z-values.

Parameters:

x – x-value.
y – y-value.
z – z-value.

Template Args:

X – x-type.
Y – y-type.
Z – z-type.

Returns:

A coordinate in the layout of type coordinate.

Raises:

std::overflow_error – If an axis is outside the signed 32-bit range.

Note

This function is equivalent to calling coordinate(x, y, z).

coordinates(start: coordinate | tuple[int, int] | tuple[int, int, int] | None = None, stop: coordinate | tuple[int, int] | tuple[int, int, int] | None = None) → list[coordinate]¶: Returns coordinates in z/y/x order from the inclusive start to the exclusive stop. None uses the frame boundary.

east(c: coordinate | tuple[int, int] | tuple[int, int, int]) → coordinate | None¶

Returns the east neighbor when both coordinates lie inside the geometry.

Parameters:: c – Base coordinate.
Returns:: Neighbor, or no value at a boundary or outside the geometry.

eastern_border_of(c: coordinate | tuple[int, int] | tuple[int, int, int]) → coordinate | None¶

Projects a coordinate to the eastern border.

Parameters:: c – Coordinate to project.
Returns:: Projection, or no value if the projection lies outside the geometry.

get_arrangement() → arrangement¶

Returns the arrangement of the shifted rows or columns.

Returns:: Arrangement fixed at construction.

get_extent() → extent¶: Returns the layout extent.

ground_coordinates(start: coordinate | tuple[int, int] | tuple[int, int, int] | None = None, stop: coordinate | tuple[int, int] | tuple[int, int, int] | None = None) → list[coordinate]¶: Returns layer-zero coordinates from the inclusive start to the exclusive stop. None uses the frame boundary. Bounds outside layer zero raise ValueError.

height() → int¶: Returns the height count.

is_above(c1: coordinate | tuple[int, int] | tuple[int, int, int], c2: coordinate | tuple[int, int] | tuple[int, int, int]) → bool¶

Returns true iff coordinate c2 is directly above coordinate c1.

Parameters:

c1 – Base coordinate.
c2 – Coordinate to test for its location in relation to c1.

Returns:

true iff c2 is directly above c1.

is_adjacent_elevation_of(c1: coordinate | tuple[int, int] | tuple[int, int, int], c2: coordinate | tuple[int, int] | tuple[int, int, int]) → bool¶

Similar to is_adjacent_of but also considers c1’s elevation, i.e., if c2 is adjacent to above(c1) or below(c1).

Parameters:

c1 – Base coordinate.
c2 – Coordinate to test for its location in relation to c1.

Returns:

true iff c2 is either directly north, east, south, or west of c1 or c1’s elevations.

is_adjacent_of(c1: coordinate | tuple[int, int] | tuple[int, int, int], c2: coordinate | tuple[int, int] | tuple[int, int, int]) → bool¶

Returns true iff coordinate c2 is either directly north, east, south, or west of coordinate c1.

Parameters:

c1 – Base coordinate.
c2 – Coordinate to test for its location in relation to c1.

Returns:

true iff c2 is either directly north, east, south, or west of c1.

is_at_any_border(c: coordinate | tuple[int, int] | tuple[int, int, int]) → bool¶

Returns whether the given coordinate is located at any of the layout’s borders where x or y are either minimal or maximal.

Parameters:: c – Coordinate to check for border location.
Returns:: true iff c is located at any of the layout’s borders.

is_at_eastern_border(c: coordinate | tuple[int, int] | tuple[int, int, int]) → bool¶

Returns whether the given coordinate is located at the layout’s eastern border where x is maximal.

Parameters:: c – Coordinate to check for border location.
Returns:: true iff c is located at the layout’s northern border.

is_at_northern_border(c: coordinate | tuple[int, int] | tuple[int, int, int]) → bool¶

Returns whether the given coordinate is located at the layout’s northern border where y is minimal.

Parameters:: c – Coordinate to check for border location.
Returns:: true iff c is located at the layout’s northern border.

is_at_southern_border(c: coordinate | tuple[int, int] | tuple[int, int, int]) → bool¶

Returns whether the given coordinate is located at the layout’s southern border where y is maximal.

Parameters:: c – Coordinate to check for border location.
Returns:: true iff c is located at the layout’s southern border.

is_at_western_border(c: coordinate | tuple[int, int] | tuple[int, int, int]) → bool¶

Returns whether the given coordinate is located at the layout’s western border where x is minimal.

Parameters:: c – Coordinate to check for border location.
Returns:: true iff c is located at the layout’s western border.

is_below(c1: coordinate | tuple[int, int] | tuple[int, int, int], c2: coordinate | tuple[int, int] | tuple[int, int, int]) → bool¶

Returns true iff coordinate c2 is directly below coordinate c1.

Parameters:

c1 – Base coordinate.
c2 – Coordinate to test for its location in relation to c1.

Returns:

true iff c2 is directly below c1.

is_crossing_layer(c: coordinate | tuple[int, int] | tuple[int, int, int]) → bool¶

Returns whether the given coordinate is located in the crossing layer at z = 1.

Parameters:: c – Coordinate to check for elevation.
Returns:: true iff c.z is 1.

is_east_of(c1: coordinate | tuple[int, int] | tuple[int, int, int], c2: coordinate | tuple[int, int] | tuple[int, int, int]) → bool¶

Returns true iff coordinate c2 is directly east of coordinate c1.

Parameters:

c1 – Base coordinate.
c2 – Coordinate to test for its location in relation to c1.

Returns:

true iff c2 is directly east of c1.

is_eastwards_of(c1: coordinate | tuple[int, int] | tuple[int, int, int], c2: coordinate | tuple[int, int] | tuple[int, int, int]) → bool¶

Returns true iff coordinate c2 is somewhere east of coordinate c1.

Parameters:

c1 – Base coordinate.
c2 – Coordinate to test for its location in relation to c1.

Returns:

true iff c2 is somewhere east of c1.

is_ground_layer(c: coordinate | tuple[int, int] | tuple[int, int, int]) → bool¶

Returns whether the given coordinate is located in the ground layer where z is minimal.

Parameters:: c – Coordinate to check for elevation.
Returns:: true iff c is in ground layer.

is_north_of(c1: coordinate | tuple[int, int] | tuple[int, int, int], c2: coordinate | tuple[int, int] | tuple[int, int, int]) → bool¶

Returns true iff coordinate c2 is directly north of coordinate c1.

Parameters:

c1 – Base coordinate.
c2 – Coordinate to test for its location in relation to c1.

Returns:

true iff c2 is directly north of c1.

is_northwards_of(c1: coordinate | tuple[int, int] | tuple[int, int, int], c2: coordinate | tuple[int, int] | tuple[int, int, int]) → bool¶

Returns true iff coordinate c2 is somewhere north of coordinate c1.

Parameters:

c1 – Base coordinate.
c2 – Coordinate to test for its location in relation to c1.

Returns:

true iff c2 is somewhere north of c1.

is_south_of(c1: coordinate | tuple[int, int] | tuple[int, int, int], c2: coordinate | tuple[int, int] | tuple[int, int, int]) → bool¶

Returns true iff coordinate c2 is directly south of coordinate c1.

Parameters:

c1 – Base coordinate.
c2 – Coordinate to test for its location in relation to c1.

Returns:

true iff c2 is directly south of c1.

is_southwards_of(c1: coordinate | tuple[int, int] | tuple[int, int, int], c2: coordinate | tuple[int, int] | tuple[int, int, int]) → bool¶

Returns true iff coordinate c2 is somewhere south of coordinate c1.

Parameters:

c1 – Base coordinate.
c2 – Coordinate to test for its location in relation to c1.

Returns:

true iff c2 is somewhere south of c1.

is_west_of(c1: coordinate | tuple[int, int] | tuple[int, int, int], c2: coordinate | tuple[int, int] | tuple[int, int, int]) → bool¶

Returns true iff coordinate c2 is directly west of coordinate c1.

Parameters:

c1 – Base coordinate.
c2 – Coordinate to test for its location in relation to c1.

Returns:

true iff c2 is directly west of c1.

is_westwards_of(c1: coordinate | tuple[int, int] | tuple[int, int, int], c2: coordinate | tuple[int, int] | tuple[int, int, int]) → bool¶

Returns true iff coordinate c2 is somewhere west of coordinate c1.

Parameters:

c1 – Base coordinate.
c2 – Coordinate to test for its location in relation to c1.

Returns:

true iff c2 is somewhere west of c1.

is_within_bounds(c: coordinate | tuple[int, int] | tuple[int, int, int]) → bool¶

Parameters:: c – Coordinate. @return Whether the geometry contains the coordinate.

last_coordinate() → coordinate | None¶: Returns the last coordinate, or None for empty geometry.

layers() → int¶: Returns the layers count.

north(c: coordinate | tuple[int, int] | tuple[int, int, int]) → coordinate | None¶

Returns the north neighbor when both coordinates lie inside the geometry.

Parameters:: c – Base coordinate.
Returns:: Neighbor, or no value at a boundary or outside the geometry.

north_east(c: coordinate | tuple[int, int] | tuple[int, int, int]) → coordinate | None¶

Returns the north-east neighbor when both coordinates lie inside the geometry.

Parameters:: c – Base coordinate.
Returns:: Neighbor, or no value at a boundary or outside the geometry.

north_west(c: coordinate | tuple[int, int] | tuple[int, int, int]) → coordinate | None¶

Returns the north-west neighbor when both coordinates lie inside the geometry.

Parameters:: c – Base coordinate.
Returns:: Neighbor, or no value at a boundary or outside the geometry.

northern_border_of(c: coordinate | tuple[int, int] | tuple[int, int, int]) → coordinate | None¶

Projects a coordinate to the northern border.

Parameters:: c – Coordinate to project.
Returns:: Projection, or no value if the projection lies outside the geometry.

resize(extent: extent | tuple[int, int] | tuple[int, int, int]) → None¶

Changes the geometry’s axis sizes.

Parameters:

extent – Axis sizes.

Raises:

std::invalid_argument – If a size exceeds the coordinate domain.
std::out_of_range – If the layer count exceeds two. The dimensions remain unchanged.

south(c: coordinate | tuple[int, int] | tuple[int, int, int]) → coordinate | None¶

Returns the south neighbor when both coordinates lie inside the geometry.

Parameters:: c – Base coordinate.
Returns:: Neighbor, or no value at a boundary or outside the geometry.

south_east(c: coordinate | tuple[int, int] | tuple[int, int, int]) → coordinate | None¶

Returns the south-east neighbor when both coordinates lie inside the geometry.

Parameters:: c – Base coordinate.
Returns:: Neighbor, or no value at a boundary or outside the geometry.

south_west(c: coordinate | tuple[int, int] | tuple[int, int, int]) → coordinate | None¶

Returns the south-west neighbor when both coordinates lie inside the geometry.

Parameters:: c – Base coordinate.
Returns:: Neighbor, or no value at a boundary or outside the geometry.

southern_border_of(c: coordinate | tuple[int, int] | tuple[int, int, int]) → coordinate | None¶

Projects a coordinate to the southern border.

Parameters:: c – Coordinate to project.
Returns:: Projection, or no value if the projection lies outside the geometry.

west(c: coordinate | tuple[int, int] | tuple[int, int, int]) → coordinate | None¶

Returns the west neighbor when both coordinates lie inside the geometry.

Parameters:: c – Base coordinate.
Returns:: Neighbor, or no value at a boundary or outside the geometry.

western_border_of(c: coordinate | tuple[int, int] | tuple[int, int, int]) → coordinate | None¶

Projects a coordinate to the western border.

Parameters:: c – Coordinate to project.
Returns:: Projection, or no value if the projection lies outside the geometry.

width() → int¶: Returns the width count.