Module Vector
Point-to-Point 2D Vectors.
All Vector methods manipulate the vector in-place AND return it.
A new instance can be created with Vector:copy().
Conversion to other formats via Vector.to_* will obviously not return a Vector ;).
Module Status: Work in progress. Compatibility: Pure Lua.
Naming convention:
All outputting methods are called to_*.
All methods that take two vectors take the vector v that the transformation
will be applied to first, and the vector w that contains the transformation
is taken as a VectorSpec "...".
In transformation methods that have two component or derivate names in their
name the first refers to w and the second to v.
i.e add_offset_to_origin
adds the raw offset of w to the raw origin of v (often called "shift").
i.e. set_origin_to_target
moves the origin of v to the absolute coordinates of the target of w.
Usage:
local Vector = require('__eradicators-library__/erlib/lua/Vector')()
Todo
| todo1 | make :to_offset_uid('spiral') reversible |
Concepts
| Vector | A two-component Vector. |
| VectorSpec | Data that can be transformed into a Vector. |
Examples
| Example1 | Create a simple area. |
Class Parent
| Vector(...) | Initializes a new vector. |
Copy
| copy(v) | A plain copy of the vector. |
Unpacking of Vector coordinates
| get_target(v) | |
| get_offset(v) | |
| get_origin(v) |
Raw coordinate manipulation
Mirror
| mirror_offset_x(v) | |
| mirror_offset_y(v) | |
| mirror_offset_xy(v) | |
| mirror_origin_x(v) | |
| mirror_origin_y(v) | |
| mirror_origin_xy(v) |
Retargeting
| set_origin_to_target_keep_target(v, ...) | recalculates the vector to point to the same target from the new origin input vectors with non-0,0 origin will be treated as absolute positions |
| null_origin_keep_target(v) | shortcut for the common null operation. |
| set_target_to_target_keep_origin(v, ...) | recalculates the offset to point at the target of @w |
| set_target_to_target_and_set_origin_to_own_target(v, ...) | in-place replaces the old vector with a new vector (target of @v -> target of @w) |
| swap_origin_with_target(v) | move the origin of @v to it's own target, and mirrors the offset so that the new target is the old origin. |
Linear Transformation
| add_offset_to_offset(v, ...) | adds components of @w to components of @v |
| add_target_to_offset(v, ...) | |
| add_offset_to_origin(v, ...) | |
| add_target_to_origin(v, ...) | |
| add_offset_both_ways(v, ...) | adds the vector @w to both sides of the vector (i.e. |
| add_target_both_ways(v, ...) | |
| scale_offset(v, n) | multiplies the offset/origin with a fixed factor |
| scale_origin(v, n) | |
| scale_both_ways(v, n) | scales the offset length by n/2 in each direction useful for expanding boxes |
| set_center_to_target(v, ...) | moves the origin of @v so that the center of the line @v_origin -> @v_target is positioned on the target of @w. |
Angle Calculation
| to_radians(v) | null is right, anti-clockwise |
| to_degrees(v) | null is up, clockwise |
| to_orientation(v) | null is up, clockwise |
| to_direction(v) | null is up, clockwise. |
| to_strict_direction(v) | null is up, clockwise. |
| from_degrees(theta, len) | these return a vector of length 1 (i.e. |
| from_radians(theta, len) | |
| from_orientation(o, len) | |
| from_direction(d, len) |
Rotational Transformation
| rotate_offset_by_degrees(v, deg) | rotates only the /offset/ part of @v |
| rotate_origin_by_degrees(v, deg, ...) | rotates the /current origin/ of @v around the given VectorSpecification |
| rotate_both_by_degrees(v, deg, ...) | rotates both the origin and target of @v around @w |
| rotate_offset_by_direction(v, dir) | |
| rotate_origin_by_direction(v, dir, ...) | |
| rotate_both_by_direction(v, dir, ...) | |
| rotate_offset_by_orientation(v, ori) | |
| rotate_origin_by_orientation(v, ori, ...) | |
| rotate_both_by_orientation(v, ori, ...) |
UID / Z×Z→N Pairing Wrappers
| to_offset_uid(v, mode) | offset → UID |
| to_origin_uid(v, mode) | |
| to_target_uid(v, mode) | |
| set_offset_from_uid(v, uid, mode) | UID → offset, origin, new |
| set_origin_from_uid(v, uid, mode) | |
| from_uid(...) |
Comparision of Vectors
| is_offset_equal(v, ...) | |
| is_origin_equal(v, ...) | |
| is_target_equal(v, ...) |
Conversion to other formats
| to_box(v) | an undecorated box (nested table) like used in data stage prototypes |
| to_area(v) | a factorio runtime area (includes "lt" and "rb" as linked shortcuts) |
| to_target_position(v) | the position of the end-point of the vector add factorio {x=,y=} table position |
| to_origin_position(v) | the position of the origin of the vector |
| to_simple_vector(v) | an undecorated vector required by some functions like teleport() |
| to_point(v) | makes the vector a point (null vector) at the position it was pointing |
| to_length(v) | The real length of the vector which replaces the __len (#) operator. |
| to_manhatten_distance(v) |
Debugging
| draw(v[, ttl=60]) | draws the vector into the world on the first surface with an admin player. |
Todo
Concepts
- Vector
-
A two-component Vector.
A Vector is a DenseArray
{dx, dy, ox, oy}, it does not have named keys or subtables.Components:
The offset:
(dx, dy)is the relative vector from the origin to the target.The origin:
(ox, oy)is the absolute point on the grid where the Vector starts. Usually(0,0).Derivates:
The target:
(ox+dx, oy+dy)is the absolute point on the grid that the Vector points at.The center:
(ox+(dx/2), oy+(dy/2))is the middle of the "line" between a Vectors origin and target.Other:
The grid origin: The origin of a grid (aka coordinate system) is always
(0,0). - VectorSpec
-
Data that can be transformed into a Vector.
Explicit or shorthand BoundingBox, explicit Position, Vector, SimpleVector or up-to-four component varargs
number, number or nil, number or nil, number or nil.Shorthand Position and SimpleVector are equivalent.
Up-to-four component varargs defaults are:
dx or 0, dy or dx or 0, ox or 0, oy or 0.
Examples
- Example1
-
Create a simple area.
Usage:
local my_vector = Vector(1,1) :set_center_to_target(0,0) :to_area() print(Hydra.line(my_vector)) > { > left_top = {x = -0.5, y = -0.5}, > right_bottom = {x = 0.5, y = 0.5} > lt = nil --[[ self.left_top ]], > rb = nil --[[ self.right_bottom ]], > }
Class Parent
- Vector(...)
-
Initializes a new vector.
Parameters:
- ...
Usage:
Vector(Area) :: a factorio area box {left_top={x=,y=},right_bottom={x=,y=}} Vector(BoundingBox) :: a factorio bounding box {{x,y},{x,y}} Vector(Position) :: a factorio position {x=,y=} Vector(Vector) :: a four component vector created by this library Vector(SimpleVector) :: a factorio two component vector {x,y} Vector(Number,Number or nil,Number or nil,Number or nil) :: Numbers are dx, dy, ox, oy :: oy defaults to ox :: ox defaults to 0 :: dy defaults to dx :: dx is mandatory
Copy
Unpacking of Vector coordinates
Raw coordinate manipulation
- null_offset(v)
-
Parameters:
- v
- null_origin(v)
-
Parameters:
- v
- set_offset_to_offset(v, ...)
-
Parameters:
- v
- ...
- set_offset_to_target(v, ...)
-
Parameters:
- v
- ...
- set_offset_to_origin(v, ...)
-
Parameters:
- v
- ...
- set_origin_to_offset(v, ...)
-
Parameters:
- v
- ...
- set_origin_to_target(v, ...)
-
Parameters:
- v
- ...
- set_origin_to_origin(v, ...)
-
Parameters:
- v
- ...
Mirror
- mirror_offset_x(v)
-
Parameters:
- v
- mirror_offset_y(v)
-
Parameters:
- v
- mirror_offset_xy(v)
-
Parameters:
- v
- mirror_origin_x(v)
-
Parameters:
- v
- mirror_origin_y(v)
-
Parameters:
- v
- mirror_origin_xy(v)
-
Parameters:
- v
Retargeting
- set_origin_to_target_keep_target(v, ...)
-
recalculates the vector to point to the same target from the new origin
input vectors with non-0,0 origin will be treated as absolute positions
Parameters:
- v
- ...
- null_origin_keep_target(v)
-
shortcut for the common null operation.
Parameters:
- v
- set_target_to_target_keep_origin(v, ...)
-
recalculates the offset to point at the target of @w
Parameters:
- v
- ...
- set_target_to_target_and_set_origin_to_own_target(v, ...)
-
in-place replaces the old vector with a new vector (target of @v -> target of @w)
Parameters:
- v
- ...
- swap_origin_with_target(v)
-
move the origin of @v to it's own target, and mirrors
the offset so that the new target is the old origin.
Parameters:
- v
Linear Transformation
- add_offset_to_offset(v, ...)
-
adds components of @w to components of @v
Parameters:
- v
- ...
- add_target_to_offset(v, ...)
-
Parameters:
- v
- ...
- add_offset_to_origin(v, ...)
-
Parameters:
- v
- ...
- add_target_to_origin(v, ...)
-
Parameters:
- v
- ...
- add_offset_both_ways(v, ...)
-
adds the vector @w to both sides of the vector (i.e. twice)
Parameters:
- v
- ...
- add_target_both_ways(v, ...)
-
Parameters:
- v
- ...
- scale_offset(v, n)
-
multiplies the offset/origin with a fixed factor
Parameters:
- v
- n
- scale_origin(v, n)
-
Parameters:
- v
- n
- scale_both_ways(v, n)
-
scales the offset length by n/2 in each direction
useful for expanding boxes
Parameters:
- v return v
- n addoffsettoorigin(v:copy():mirroroffsetxy():scaleoffset(0.5*n - 0.5)):scale_offset(n)
- set_center_to_target(v, ...)
-
moves the origin of @v so that the center of the line @v_origin -> @v_target
is positioned on the target of @w.
Parameters:
- v
- ...
Usage:
print(Hydra.line(Vector(3):set_center_to_target(0):to_box())) > {{-1.5, -1.5}, {1.5, 1.5}}
Angle Calculation
- to_radians(v)
-
null is right, anti-clockwise
Parameters:
- v
- to_degrees(v)
-
null is up, clockwise
Parameters:
- v
- to_orientation(v)
-
null is up, clockwise
Parameters:
- v
- to_direction(v)
-
null is up, clockwise.
Approximate direction from eight 45° octants.
Parameters:
- v
- to_strict_direction(v)
-
null is up, clockwise.
Precise direction from four straight lines and four 90° quadrants.
Parameters:
- v
- from_degrees(theta, len)
-
these return a vector of length 1 (i.e. the vector {0,-1} rotated accordingly)
Parameters:
- theta
- len up/clockwise
- from_radians(theta, len)
-
Parameters:
- theta
- len right anti-clockwise
- from_orientation(o, len)
-
Parameters:
- o
- len up/clockwise
- from_direction(d, len)
-
Parameters:
- d
- len up/clockwise
Rotational Transformation
- rotate_offset_by_degrees(v, deg)
-
rotates only the /offset/ part of @v
Parameters:
- v
- deg
- rotate_origin_by_degrees(v, deg, ...)
-
rotates the /current origin/ of @v around the given VectorSpecification
Parameters:
- v
- deg
- ...
- rotate_both_by_degrees(v, deg, ...)
-
rotates both the origin and target of @v around @w
Parameters:
- v
- deg
- ...
- rotate_offset_by_direction(v, dir)
-
Parameters:
- v
- dir
- rotate_origin_by_direction(v, dir, ...)
-
Parameters:
- v
- dir
- ...
- rotate_both_by_direction(v, dir, ...)
-
Parameters:
- v
- dir
- ...
- rotate_offset_by_orientation(v, ori)
-
Parameters:
- v
- ori
- rotate_origin_by_orientation(v, ori, ...)
-
Parameters:
- v
- ori
- ...
- rotate_both_by_orientation(v, ori, ...)
-
Parameters:
- v
- ori
- ...
UID / Z×Z→N Pairing Wrappers
- to_offset_uid(v, mode)
-
offset → UID
Parameters:
- to_origin_uid(v, mode)
-
Parameters:
- v
- mode
- to_target_uid(v, mode)
-
Parameters:
- v
- mode
- set_offset_from_uid(v, uid, mode)
-
UID → offset, origin, new
Parameters:
- v
- uid
- mode
- set_origin_from_uid(v, uid, mode)
-
Parameters:
- v
- uid
- mode
- from_uid(...)
-
Parameters:
- ...
Returns:
-
Vector
a fresh vector from the null point to UID
Comparision of Vectors
- is_offset_equal(v, ...)
-
Parameters:
- v
- ...
- is_origin_equal(v, ...)
-
Parameters:
- v
- ...
- is_target_equal(v, ...)
-
Parameters:
- v
- ...
Conversion to other formats
- to_box(v)
-
an undecorated box (nested table) like used in data stage prototypes
Parameters:
- v
- to_area(v)
-
a factorio runtime area (includes "lt" and "rb" as linked shortcuts)
Parameters:
- v
- to_target_position(v)
-
the position of the end-point of the vector
add factorio {x=,y=} table position
Parameters:
- v
- to_origin_position(v)
-
the position of the origin of the vector
Parameters:
- v
- to_simple_vector(v)
-
an undecorated vector required by some functions like teleport()
Parameters:
- v
- to_point(v)
-
makes the vector a point (null vector) at the position it was pointing
Parameters:
- v
- to_length(v)
-
The real length of the vector which replaces the __len (#) operator.
Parameters:
- v
- to_manhatten_distance(v)
-
Parameters:
- v