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
.
- 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 abot_right
point, as well as an offset position. Provides an abstraction forCollisionSet
and a number of convenience functions.- static from_other(aabb: list[float] | tuple[float]) AABB
Converts a
PrimitiveAABB
to anAABB
.- 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 4Vector
objects for each of the AABB corners.
- overlaps(other: Shape) bool
Determines if this
Shape
overlaps with anotherShape
.- 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 ofDirection
, such that2
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.
- class Rectangle(position: Vector, width: float, height: float, angle: float)
A rotate-able rectangle abstraction class, distinguished from
AABB
. Specified as awidth
,height
, anangle
, and aposition
(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 4Vector
objects for each of the Rectangle’s corners.
- overlaps(other: Shape) bool
Determines if this
Shape
overlaps with anotherShape
.- 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 ofDirection
, such that2
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 usingBlueprint
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
andb
.
- 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 AABBa
.- 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 AABBb
.- 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 radiusr
centered around pointc
. Ifc
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 radiusr
at pointc
. 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 areNone
, thenNone
is returned.
- 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.