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

null_offset(v)  
null_origin(v)  
set_offset_to_offset(v, ...)  
set_offset_to_target(v, ...)  
set_offset_to_origin(v, ...)  
set_origin_to_offset(v, ...)  
set_origin_to_target(v, ...)  
set_origin_to_origin(v, ...)  

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

todo1
make :to_offset_uid('spiral') reversible

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

copy(v)
A plain copy of the vector. (in case the original is still needed)

Parameters:

  • v

Unpacking of Vector coordinates

get_target(v)
 

Parameters:

  • v
get_offset(v)
 

Parameters:

  • v
get_origin(v)
 

Parameters:

  • v

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

Debugging

draw(v[, ttl=60])
draws the vector into the world on the first surface with an admin player.

Parameters:

  • v Vector
  • ttl Integer How long the render will live. (default 60)
generated by LDoc 1.4.6 Last updated 2021-09-10 19:51:19