Area.Position module

Tools for working with <x,y> coordinates.

See also

Usage

local Position = require('__stdlib__/stdlib/area/position')

Tables

Metamethods Position tables are returned with these metamethods attached.

Fields

epsilon Machine Epsilon

Constructor Methods

construct(x, y) Creates a table representing the position from x and y.
from_key(pos_string) Converts a string key position to a position.
from_string(pos_string) Converts a position string to a position.
new(pos) Returns a correctly formated position object.
set(pos) Load the metatable into the passed position without creating a new one.

Position Methods

abs(pos) Abs x, y values
add(pos1, ...) Addition of two positions.
average(positions) Return the average position of the passed positions.
between(pos1, pos2) The middle of two positions.
ceil(pos) Ceil x, y values
center(pos) Gets the center position of the tile where the given position resides.
closest(pos1, positions) Return the closest position to the first position.
divide(pos1, ...) Division of two positions.
farthest(pos1, positions) Return the farthest position from the first position.
floor(pos) Floor x, y values
intersection(pos1_start, pos1_end, pos2_start, pos2_end) The intersection of 4 positions.
lerp(pos1, pos2, alpha) Lerp position of pos1 and pos2.
max(positions) Return the maximum position of the passed positions.
max_xy(positions) Return a position created from the largest x, y values in the passed positions.
min(positions) Return the minimum position of the passed positions.
min_xy(positions) Return a position created from the smallest x, y values in the passed positions.
mod(pos1, ...) Modulo of two positions.
multiply(pos1, ...) Multiplication of two positions.
normalize(pos) Normalizes a position by rounding it to 2 decimal places
offset_along_line(pos1, pos2, distance_from_pos2) Returns the position along line between source and target, at the distance from target.
perpendicular(pos) Perpendicular position
projection(pos1, pos2) The projection point of two positions.
recall(pos) Recalls the stored position.
reflection(pos1, pos2) The reflection point or two positions.
round(pos) Rounds a positions points to the closes integer
store(pos) Stores the position for recall later, not deterministic.
subtract(pos1, ...) Subtraction of two positions..
swap(pos) Swap the x and y coordinates.
translate(pos, direction, distance) Translates a position in the given direction.
trim(pos, max_len) Trim the position to a length.
unary(pos) Flip the signs of the position.

Position Conversion Methods

from_chunk_position(pos) Gets the left top tile position of a chunk from the chunk position.
from_pixels(pos) Convert position from pixels
to_chunk_position(pos) Gets the chunk position of a chunk where the specified position resides.
to_pixels(pos) Convert to pixels from position

Area Conversion Methods

expand_to_area(pos, radius) Expands a position to a square area.
to_area(pos, width, height) Expands a position into an area by setting pos to left_top.
to_chunk_area(pos) Get the chunk area the specified position is in.
to_tile_area(pos) Converts a tile position to the area of the tile it is in.

Position Functions

angle(pos1, pos2) The angle between two positions
atan2(pos1, pos2) Return the atan2 of 2 positions.
complex_direction_to(pos1, pos2, eight_way) Returns the direction to a position.
cross(pos1, pos2) Return the cross product of two positions.
direction_to(pos1, pos2) Returms the direction to a position using simple delta comparisons.
distance(pos1[, pos2={x=0]) Calculates the Euclidean distance between two positions.
distance_squared(pos1[, pos2]) Calculates the Euclidean distance squared between two positions, useful when sqrt is not needed.
equals(pos1, pos2) Tests whether or not the two given positions are equal.
increment(pos[, inc_x=0][, inc_y=0][, increment_initial=false]) Increment a position each time it is called.
increment_closure([new_inc_x=0][, new_inc_y=0]) A closure which the increment function returns.
inside(pos, area) Is a position inside of an area.
is_position(pos) Is this a full position
is_set(pos) Does the position have the class attached
is_zero(pos) Is this position {0, 0}.
len(pos) Gets the length of a position
len_squared(pos) Gets the squared length of a position
less_than(pos1, pos2) Is pos1 less than pos2.
less_than_eq(pos1, pos2) Is pos1 less than or equal to pos2.
manhattan_distance(pos1[, pos2]) Calculates the manhatten distance between two positions.
pack(pos) Packs a position into an array.
to_key(pos) Converts a position to a string suitable for using as a table index.
to_string(pos) Converts a position to a string.
unpack(pos) Unpack a position into a tuple.

Tables

# Metamethods

Position tables are returned with these metamethods attached.

Methods that return a position will return a NEW position without modifying the passed positions.

Fields:
  • __class
  • __index : If key is not found, see if there is one availble in the Position module.
  • __add : Adds two position together. Returns a new position.
  • __sub : Subtracts one position from another. Returns a new position.
  • __mul : Multiply 2 positions. Returns a new position.
  • __div : Divide 2 positions. Returns a new position.
  • __mod : Modulo of 2 positions. Returns a new position.
  • __unm : Unary Minus of a position. Returns a new position.
  • __len : Length of a single position.
  • __eq : Are two positions at the same spot.
  • __lt : Is position1 less than position2.
  • __le : Is position1 less than or equal to position2.
  • __tostring : Returns a string representation of the position
  • __concat : calls tostring on both sides of concact.
  • __call : copy the position.

Fields

# epsilon

Machine Epsilon

See also:

Constructor Methods

# construct(x, y)

Creates a table representing the position from x and y.

Parameters: Returns:
# from_key(pos_string)

Converts a string key position to a position.

Parameters:
  • pos_string : (string) the position to convert
Returns:
# from_string(pos_string)

Converts a position string to a position.

Parameters:
  • pos_string : (string) the position to convert
Returns:
# new(pos)

Returns a correctly formated position object.

Parameters:
  • pos : (Position) the position table or array to convert
Returns: Usage:
Position.new({0, 0}) -- returns {x = 0, y = 0}
# set(pos)

Load the metatable into the passed position without creating a new one.

Always assumes a valid position is passed

Parameters:
  • pos : (Position) the position to set the metatable onto
Returns:
  • (Position) the position with metatable attached

Position Methods

# abs(pos)

Abs x, y values

Parameters: Returns:
# add(pos1, ...)

Addition of two positions.

Parameters: Returns:
# average(positions)

Return the average position of the passed positions.

Parameters:
  • positions : (array) array of Concepts.Position
Returns:
# between(pos1, pos2)

The middle of two positions.

Parameters: Returns:
  • (Position) pos1 the middle of two positions
# ceil(pos)

Ceil x, y values

Parameters: Returns:
# center(pos)

Gets the center position of the tile where the given position resides.

Parameters: Returns:
  • (Position) the position at the center of the tile
# closest(pos1, positions)

Return the closest position to the first position.

Parameters:
  • pos1 : (Positions) The position to find the closest too
  • positions : (array) array of Concepts.Position
Returns:
# divide(pos1, ...)

Division of two positions.

Parameters: Returns:
# farthest(pos1, positions)

Return the farthest position from the first position.

Parameters:
  • pos1 : (Positions) The position to find the farthest from
  • positions : (array) array of Concepts.Position
Returns:
# floor(pos)

Floor x, y values

Parameters: Returns:
# intersection(pos1_start, pos1_end, pos2_start, pos2_end)

The intersection of 4 positions.

Parameters:
  • pos1_start
  • pos1_end
  • pos2_start
  • pos2_end
Returns:
# lerp(pos1, pos2, alpha)

Lerp position of pos1 and pos2.

Parameters: Returns:
# max(positions)

Return the maximum position of the passed positions.

Parameters:
  • positions : (array) array of Concepts.Position
Returns:
# max_xy(positions)

Return a position created from the largest x, y values in the passed positions.

Parameters:
  • positions : (array) array of Concepts.Position
Returns:
# min(positions)

Return the minimum position of the passed positions.

Parameters:
  • positions : (array) array of Concepts.Position
Returns:
# min_xy(positions)

Return a position created from the smallest x, y values in the passed positions.

Parameters:
  • positions : (array) array of Concepts.Position
Returns:
# mod(pos1, ...)

Modulo of two positions.

Parameters: Returns:
# multiply(pos1, ...)

Multiplication of two positions.

Parameters: Returns:
# normalize(pos)

Normalizes a position by rounding it to 2 decimal places

Parameters: Returns:
# offset_along_line(pos1, pos2, distance_from_pos2)

Returns the position along line between source and target, at the distance from target.

Parameters:
  • pos1 : (Position) where the line starts and extends from.
  • pos2 : (Position) where the line ends and is offset back from.
  • distance_from_pos2 : (number) backwards from pos1 for the new position.
Returns:
  • (Position) a point along line between source and target, at requested offset back from target.
# perpendicular(pos)

Perpendicular position

Parameters: Returns:
# projection(pos1, pos2)

The projection point of two positions.

Parameters: Returns:
# recall(pos)

Recalls the stored position.

Parameters: Returns:
# reflection(pos1, pos2)

The reflection point or two positions.

Parameters: Returns:
# round(pos)

Rounds a positions points to the closes integer

Parameters: Returns:
# store(pos)

Stores the position for recall later, not deterministic.

Only the last position stored is saved.

Parameters:
# subtract(pos1, ...)

Subtraction of two positions..

Parameters: Returns:
# swap(pos)

Swap the x and y coordinates.

Parameters: Returns:
# translate(pos, direction, distance)

Translates a position in the given direction.

Parameters: Returns:
# trim(pos, max_len)

Trim the position to a length.

Parameters:
# unary(pos)

Flip the signs of the position.

Parameters: Returns:
  • Concenpts.position with flipped signs

Position Conversion Methods

# from_chunk_position(pos)

Gets the left top tile position of a chunk from the chunk position.

Parameters: Returns:
# from_pixels(pos)

Convert position from pixels

Parameters: Returns:
# to_chunk_position(pos)

Gets the chunk position of a chunk where the specified position resides.

Parameters:
  • pos : (Position) a position residing somewhere in a chunk
Returns: Usage:
local chunk_x = Position.chunk_position(pos).x
# to_pixels(pos)

Convert to pixels from position

Parameters: Returns:

Area Conversion Methods

# expand_to_area(pos, radius)

Expands a position to a square area.

Parameters:
  • pos : (Position) the position to expand into an area
  • radius : (number) half of the side length of the area
Returns:
# to_area(pos, width, height)

Expands a position into an area by setting pos to left_top.

Parameters: Returns:
# to_chunk_area(pos)

Get the chunk area the specified position is in.

Parameters: Returns:
# to_tile_area(pos)

Converts a tile position to the area of the tile it is in.

Parameters: Returns:

Position Functions

# angle(pos1, pos2)

The angle between two positions

Parameters: Returns:
# atan2(pos1, pos2)

Return the atan2 of 2 positions.

Parameters: Returns:
# complex_direction_to(pos1, pos2, eight_way)

Returns the direction to a position.

Parameters: Returns:
# cross(pos1, pos2)

Return the cross product of two positions.

Parameters: Returns:
# direction_to(pos1, pos2)

Returms the direction to a position using simple delta comparisons.

Parameters: Returns:
# distance(pos1[, pos2={x=0])

Calculates the Euclidean distance between two positions.

Parameters: Returns:
  • (number) the euclidean distance
# distance_squared(pos1[, pos2])

Calculates the Euclidean distance squared between two positions, useful when sqrt is not needed.

Parameters: Returns:
  • (number) the square of the euclidean distance
# equals(pos1, pos2)

Tests whether or not the two given positions are equal.

Parameters: Returns:
  • (boolean) true if positions are equal
# increment(pos[, inc_x=0][, inc_y=0][, increment_initial=false])

Increment a position each time it is called.

This can be used to increment or even decrement a position quickly.

Do not store function closures in the global object; use them in the current tick.

Parameters:
  • pos : (Position) the position to start with
  • inc_x : (number) optional increment x by this amount (default: 0)
  • inc_y : (number) optional increment y by this amount (default: 0)
  • increment_initial : (boolean) Whether the first use should be incremented (default: false)
Returns: Usage:
local next_pos = Position.increment({0,0})
for i = 1, 5 do next_pos(0,1) -- returns {x = 0, y = 1} {x = 0, y = 2} {x = 0, y = 3} {x = 0, y = 4} {x = 0, y = 5}
local next_pos = Position.increment({0, 0}, 1)
next_pos() -- returns {1, 0}
next_pos(0, 5) -- returns {1, 5}
next_pos(nil, 5) -- returns {2, 10}
local next_pos = Position.increment({0, 0}, 0, 1)
surface.create_entity{name = 'flying-text', text = 'text', position = next_pos()}
surface.create_entity{name = 'flying-text', text = 'text', position = next_pos()} -- creates two flying text entities 1 tile apart
# increment_closure([new_inc_x=0][, new_inc_y=0])

A closure which the increment function returns.

Do not call this directly and do not store this in the global object.

Parameters:
  • new_inc_x : (number) (default: 0)
  • new_inc_y : (number) (default: 0)
Returns: See also:
# inside(pos, area)

Is a position inside of an area.

Parameters: Returns:
  • (boolean) Is the position inside of the area.
# is_position(pos)

Is this a full position

Parameters: Returns:
# is_set(pos)

Does the position have the class attached

Parameters: Returns:
# is_zero(pos)

Is this position {0, 0}.

Parameters: Returns:
# len(pos)

Gets the length of a position

Parameters: Returns:
# len_squared(pos)

Gets the squared length of a position

Parameters: Returns:
# less_than(pos1, pos2)

Is pos1 less than pos2.

Parameters: Returns:
# less_than_eq(pos1, pos2)

Is pos1 less than or equal to pos2.

Parameters: Returns:
# manhattan_distance(pos1[, pos2])

Calculates the manhatten distance between two positions.

Parameters: Returns:
  • (number) the manhatten distance
See also:
# pack(pos)

Packs a position into an array.

Parameters: Returns:
# to_key(pos)

Converts a position to a string suitable for using as a table index.

Parameters:
  • pos : (Position) the position to convert
Returns:
# to_string(pos)

Converts a position to a string.

Parameters:
  • pos : (Position) the position to convert
Returns:
  • (string) string representation of the position
# unpack(pos)

Unpack a position into a tuple.

Parameters:
  • pos : (Position) the position to unpack
Returns:
  • (tuple) x, y