utils

Provides a number of common utility functions. These are primarily used internally by Draftsman, but can be useful outside of that scope and are provided to the user as-is.

Abstract Shape Classes

class Shape(position: Vector)

Abstract Shape class. Must be overwritten with an implementation. Contains a single attribute, a PrimitiveVector position.

abstract overlaps(other: Shape) → bool

Determines if this Shape overlaps with another Shape.

Parameters:

other – The other Shape to check for intersection.

Returns:

True if the two shapes overlap, False otherwise.

class AABB(x1: float, y1: float, x2: float, y2: float, position: Vector = [0, 0])

Axis-Aligned Bounding-Box abstraction class. Contains a top_left point and a bot_right point, as well as an offset position. Provides an abstraction for CollisionSet and a number of convenience functions.

static from_other(aabb: list[float] | tuple[float]) → AABB

Converts a PrimitiveAABB to an AABB.

Parameters:

aabb – A PrimitiveAABB to convert from.

Returns:

An AABB instance.

get_bounding_box() → AABB

Returns the minimum-encompassing bounding box around this AABB, which happens to be an new AABB offset by this AABB’s position. Used for broadphase collision-checking in SpatialDataStructure.

Returns:

A new AABB object with it’s top left and bottom right offset by this AABB’s position, and the new AABB’s position at (0, 0).

get_points() → list[Vector]

Returns all 4 points associated with the corners of the AABB, used for determining collision.

Returns:

a list of 4 Vector objects for each of the AABB corners.

overlaps(other: Shape) → bool

Determines if this Shape overlaps with another Shape.

Parameters:

other – The other Shape to check for intersection.

Returns:

True if the two shapes overlap, False otherwise.

rotate(amt: int) → AABB

Rotates the AABB by increments of 90 degrees and returns a new transformed instance.

amt is expressed in increments of Direction, such that 2 is a rotation of 90 degrees clockwise and -2 is a rotation of 90 degrees counter-clockwise.

Raises:

ValueError – If amt is odd, as AABB’s cannot be rotated by 45 degrees.

Parameters:

amt – The amount to rotate, expressed as an increments of 45 degrees.

property world_bot_right: PrimitiveVector

Gets the bottom right of the AABB, as offset by it’s position. As the attribute suggests, this is typically the top-left of the box in world space. Read only.

Type:

PrimitiveVector

property world_top_left: PrimitiveVector

Gets the top left of the AABB, as offset by it’s position. As the attribute suggests, this is typically the top-left of the box in world space. Read only.

Type:

PrimitiveVector

class Rectangle(position: Vector, width: float, height: float, angle: float)

A rotate-able rectangle abstraction class, distinguished from AABB. Specified as a width, height, an angle, and a position (it’s center).

get_bounding_box() → AABB

Returns the minimum-encompassing bounding box around this Rectangle. Used for broadphase collision-checking in SpatialDataStructure.

Returns:

A new AABB object that circumscribes this Rectangle, with the returned AABB’s position at (0, 0).

get_points() → list[Sequence[float, float]]

Returns all 4 points associated with the corners of the Rectangle, used for determining collision.

Returns:

a list of 4 Vector objects for each of the Rectangle’s corners.

overlaps(other: Shape) → bool

Determines if this Shape overlaps with another Shape.

Parameters:

other – The other Shape to check for intersection.

Returns:

True if the two shapes overlap, False otherwise.

rotate(amt: int) → Rectangle

Rotates the Rectangle by increments of 45 degrees and returns a new transformed instance.

amt is expressed in increments of Direction, such that 2 is a rotation of 90 degrees clockwise and -2 is a rotation of 90 degrees counter-clockwise.

Parameters:

amt – The amount to rotate, expressed as an increments of 45 degrees.

Encoding/Decoding Operations

string_to_JSON(string: str) → dict

Decodes a Factorio Blueprint string to a readable JSON Dict. Follows the data format specification here.

For the inverse operation, see JSON_to_string().

Parameters:

string – The input Factorio blueprint string.

Returns:

A JSON dict with the blueprint’s components as keys.

Raises:

MalformedBlueprintStringError – If the input string is not decodable to a JSON object.

JSON_to_string(JSON: dict) → str

Encodes a JSON dict to a Factorio-readable blueprint string.

Follows the data format specification here.

For the inverse operation, see string_to_JSON().

Note

This function does not verify the data before encoding it. Attempting to import an incorrectly formatted blueprint dict will usually result with an error in Factorio. If you need format validation, consider using Blueprint instead.

Parameters:

JSON – The input JSON dict object.

Returns:

A str which can be imported into Factorio.

encode_version(major: int, minor: int, patch: int = 0, dev_ver: int = 0) → int

Converts version components to version number.

Encodes 4 16-bit version numbers into a 64 bit unsigned integer used to specify the version of a Factorio Blueprint or Blueprint Book.

For the inverse operation, see decode_version().

Parameters:

• major – Major version number.

• minor – Minor version number.

• patch – Patch version number.

• dev_ver – Development version number, used internally by Factorio.

Returns:

A 64 bit int with all components specified.

decode_version(version_number: int) → tuple[int, int, int, int]

Converts version number to version components. Decodes a 64 bit unsigned integer into 4 unsigned shorts and returns them as a 4-length tuple, which is usually more readable than the combined format.

For the inverse operation, see encode_version().

Parameters:

version_number – The version number to decode.

Returns:

a 4 length tuple in the format (major, minor, patch, dev_ver).

version_string_to_tuple(version_string: str) → tuple

Converts a version string to a tuple.

Used extensively when parsing mod versions when updating the package’s data, provided to the user for convinience. Splits a string by the dot character and converts each component to an int.

For the inverse operation, see version_tuple_to_string().

Parameters:

version_string – The version string to separate.

Returns:

A n-length tuple of the format (a, b, c) from "a.b.c"

version_tuple_to_string(version_tuple: tuple) → str

Converts a version tuple to a string.

Converts each element of the tuple to a string and then joins them with the ‘.’ character.

For the inverse operation, see, version_string_to_tuple().

Parameters:

version_tuple – The n-length tuple to interpret.

Returns:

A str of the format "a.b.c" from (a, b, c)

Vector Operations

distance(point1: PrimitiveVector, point2: PrimitiveVector) → float

Gets the Euclidean distance between two points. This is mostly just for Python 2 compatability.

Parameters:

• point1 – The first point to check between.

• point2 – The first point to check between.

Returns:

The distance between.

rotate_vector(a: PrimitiveVector, angle: float) → PrimitiveVector

Rotate a given vector by angle radians around the origin.

Parameters:

• a – The vector to rotate.

• angle – The angle to rotate, in radians.

Returns:

A new PrimitiveVector with the resultant rotation.

dot_product(a: PrimitiveVector, b: PrimitiveVector) → float

Gets the dot product between two 2D vectors.

Parameters:

a – The first vector.

Parma b:

The second vector.

Returns:

The dot product of a and b.

magnitude(a: PrimitiveVector) → float

Gets the magnitude of a point.

Parameters:

a – The input vector to get the magnitude of.

Returns:

The distance from the origin of point a.

normalize(a: PrimitiveVector) → PrimitiveVector

Normalizes a vector such that it’s magnitude is equal to 1.

Parameters:

a – The input vector to normalize.

Returns:

A new PrimitiveVector equivalent to normalized a.

perpendicular(a: PrimitiveVector) → PrimitiveVector

Returns a perpendicular 2D vector from another vector. Used to generate normal vectors for the Separating Axis Theorem.

Parameters:

a – The original vector to calculate from.

Returns:

A perpendicular vector to a.

Collision Functions

point_in_aabb(p: PrimitiveVector, a: AABB) → bool

Checks to see if a PrimitiveVector p is located inside AABB a.

Parameters:

• p – A Vector with a first and second element.

• a – An AABB with the region to check against.

Returns:

True if the point is inside the box, False otherwise.

aabb_overlaps_aabb(a: AABB, b: AABB) → bool

Checks to see if AABB a overlaps AABB b.

Parameters:

• a – 2-Dimensional list where the first pair is the minimum coordinate and the second pair is the maximum coordinate.

• b – Another AABB of the same format as a.

Returns:

True if they overlap, False otherwise.

point_in_circle(p: PrimitiveVector, r: float, c: PrimitiveVector = (0, 0)) → bool

Checks to see if a point p lies within radius r centered around point c. If c is not provided, the origin is assumed.

Parameters:

• p – A point sequence with a first and second element.

• r – The radius of the circle.

• c – A point sequence with a first and second element.

Returns:

True if the point is within the circle, False otherwise.

aabb_overlaps_circle(a: AABB, r: float, c: PrimitiveVector) → bool

Checks to see if an AABB a overlaps a circle with radius r at point c. Algorithm pulled from https://stackoverflow.com/a/402010/8167625

Parameters:

• a – 2-Dimensional list where the first pair is the minimum coordinate and the second pair is the maximum coordinate.

• r – The radius of the circle.

• c – The center of the circle. Defaults to the origin if not specified.

Returns:

True if the two shapes overlap, False otherwise.

rect_overlaps_rect(a: Rectangle, b: Rectangle) → bool

Checks to see whether or not two (rotatable) Rectangles intersect with each other. Sourced from: https://github.com/qwertyquerty/collision/blob/master/collision/util.py

Parameters:

• a – The first Recangle to check.

• b – The second Recangle to check.

Returns:

True if the two shapes overlap, False otherwise.

extend_aabb(a: AABB | None, b: AABB | None) → AABB | None

Gets the minimum AABB that encompasses two other bounding boxes. Used to ‘grow’ the size of a bounding box to encompass both inputs. If one of the inputs is None, then the opposite is returned; if both are None, then None is returned.

Parameters:

• a – The first AABB to extend.

• b – The second AABB to extend.

Returns:

The minumum bounding AABB between the two inputs.

aabb_to_dimensions(aabb: AABB) → tuple[int, int]

Gets the tile-dimensions of an AABB, or the minimum number of tiles across each axis that the box would have to take up. If the input aabb is None, the function returns (0, 0).

Parameters:

aabb – 2-Dimensional list where the first pair is the minimum coordinate and the second pair is the maximum coordinate.

Returns:

a tuple of the form (tile_width, tile_height)

flatten_entities(entities)

Iterates over a list of entities with nested structures and returns a 1D, “flattened” list of those entities.

Parameters:

entities – The list of entities to flatten.

Returns:

A list containing all the entities in depth-first sequence.

Miscellaneous

@reissue_warnings

Function decorator that catches all warnings issued from a function and re-issues them to the calling function.

Parameters:

func – The function who’s errors are caught and re-issued.

Returns:

The result of the function.