Area.Position module

Tools for working with <x,y> coordinates.

See also

• Area.Area
• Concepts.Position
• defines.direction

Usage

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

Constructor Methods

new(pos)	Returns a correctly formated position object.
construct(x, y)	Creates a table representing the position from x and y.
update(pos, x, y)	Update a position in place without returning a new position.
load(pos)	Load the metatable into the passed position without creating a new one.
from_string(pos_string)	Converts a position string to a position.
from_key(pos_string)	Converts a string key position to a position.
from_chunk_position(pos)	Gets the left top tile position of a chunk from the chunk position.
from_pixels(pos)	Convert position from pixels

Metamethods

Metamethods	Position tables are returned with these metamethods attached.

Position Methods

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

Position Mutate Methods

normalized(pos)	Normalizes a position by rounding it to 2 decimal places.
absed(pos)	Abs x, y values
ceiled(pos)	Ceil x, y values in place.
floored(pos)	Floor x, y values.
centered(pos)	The center position of the tile where the given position resides.
rounded(pos)	Rounds a positions points to the closest integer.
swapped(pos)	Swap the x and y coordinates.
flipped(pos)	Flip the signs of the position.

Position Conversion Methods

to_pixels(pos)	Convert to pixels from position
to_chunk_position(pos)	Gets the chunk position of a chunk where the specified position resides.

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_tile_area(pos)	Converts a tile position to the area of the tile it is in.
to_chunk_area(pos)	Get the chunk area the specified position is in.
chunk_position_to_chunk_area(pos)	Get the chunk area for the specified chunk position.

Position Functions

len_squared(pos)	Gets the squared length of a position
len(pos)	Gets the length of a position
to_string(pos)	Converts a position to a string.
to_string_xy(pos)	Converts a position to an x, y string.
to_key(pos)	Converts a position to a string suitable for using as a table index.
unpack(pos)	Unpack a position into a tuple.
pack(pos)	Packs a position into an array.
is_zero(pos)	Is this position {0, 0}.
inside(pos, area)	Is a position inside of an area.
is_simple_position(pos)	Is this a simple position.
is_complex_position(pos)	Is this a complex position.
is_Position(pos)	Does the position have the class attached
is_position(pos)	Is this any position
atan2(pos1, pos2)	Return the atan2 of 2 positions.
angle(pos1, pos2)	The angle between two positions
cross(pos1, pos2)	Return the cross product of two positions.
equals(pos1, pos2)	Tests whether or not the two given positions are equal.
less_than(pos1, pos2)	Is pos1 less than pos2.
less_than_eq(pos1, pos2)	Is pos1 less than or equal to pos2.
distance_squared(pos1[, pos2])	Calculates the Euclidean distance squared between two positions, useful when sqrt is not needed.
distance(pos1[, pos2={x=0])	Calculates the Euclidean distance between two positions.
manhattan_distance(pos1[, pos2])	Calculates the manhatten distance between two positions.
direction_to(pos1, pos2)	Returms the direction to a position using simple delta comparisons.
complex_direction_to(pos1, pos2, eight_way)	Returns the direction to a position.
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.

Constructor Methods

# new(pos)

Returns a correctly formated position object.

Parameters:

• pos : (Position) the position table or array to convert

Returns:

• (Position)

Usage:

Position.new({0, 0}) -- returns {x = 0, y = 0}

# construct(x, y)

Creates a table representing the position from x and y.

Parameters:

• x : (number) x-position
• y : (number) y-position

Returns:

• (Position)

# update(pos, x, y)

Update a position in place without returning a new position.

Parameters:

• pos : (Position)
• x : (number)
• y : (number)

Returns:

• Concepts.Position the passed position updated.

# load(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

# from_string(pos_string)

Converts a position string to a position.

Parameters:

• pos_string : (string) the position to convert

Returns:

• (Position)

# from_key(pos_string)

Converts a string key position to a position.

Parameters:

• pos_string : (string) the position to convert

Returns:

• (Position)

# from_chunk_position(pos)

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

Parameters:

• pos : (Position)

Returns:

• (Position)

# from_pixels(pos)

Convert position from pixels

Parameters:

• pos : (Position)

Returns:

• (Position) pos

Metamethods

# 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.
• __debugline

Position Methods

# add(pos1, ...)

Addition of two positions.

Parameters:

• pos1 : (Position)
• ... : (Position or number) position or x, y values.

Returns:

• (Position) pos1 with pos2 added

# subtract(pos1, ...)

Subtraction of two positions..

Parameters:

• pos1 : (Position)
• ... : (Position or number) position or x, y values

Returns:

• (Position) pos1 with pos2 subtracted

# multiply(pos1, ...)

Multiplication of two positions.

Parameters:

• pos1 : (Position)
• ... : (Position or number) position or x, y values

Returns:

• (Position) pos1 multiplied by pos2

# divide(pos1, ...)

Division of two positions.

Parameters:

• pos1 : (Position)
• ... : (Position or number) position or x, y values

Returns:

• (Position) pos1 divided by pos2

# mod(pos1, ...)

Modulo of two positions.

Parameters:

• pos1 : (Position)
• ... : (Position or number) position or x, y values

Returns:

• (Position) pos1 modulo pos2

# 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:

• (Position)

# 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:

• (Position)

# between(pos1, pos2)

The middle of two positions.

Parameters:

• pos1 : (Position)
• pos2 : (Position)

Returns:

• (Position) pos1 the middle of two positions

# projection(pos1, pos2)

The projection point of two positions.

Parameters:

• pos1 : (Position)
• pos2 : (Position)

Returns:

• (Position) pos1 projected

# reflection(pos1, pos2)

The reflection point or two positions.

Parameters:

• pos1 : (Position)
• pos2 : (Position)

Returns:

• (Position) pos1 reflected

# store(pos)

Stores the position for recall later, not deterministic.

Only the last position stored is saved.

Parameters:

• pos : (Position)

# recall(pos)

Recalls the stored position.

Parameters:

• pos : (Position)

Returns:

• (Position) the stored position

# normalize(pos)

Normalizes a position by rounding it to 2 decimal places.

Parameters:

• pos : (Position)

Returns:

• (Position) a new normalized position

# abs(pos)

Abs x, y values

Parameters:

• pos : (Position)

Returns:

• (Position)

# ceil(pos)

Ceil x, y values.

Parameters:

• pos : (Position)

Returns:

• (Position)

# floor(pos)

Floor x, y values.

Parameters:

• pos : (Position)

Returns:

• (Position)

# center(pos)

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

Parameters:

• pos : (Position)

Returns:

• (Position) A new position at the center of the tile

# round(pos)

Rounds a positions points to the closest integer.

Parameters:

• pos : (Position)

Returns:

• (Position) A new position rounded

# perpendicular(pos)

Perpendicular position.

Parameters:

• pos : (Position)

Returns:

• (Position) pos

# swap(pos)

Swap the x and y coordinates.

Parameters:

• pos : (Position)

Returns:

• (Position) A new position with x and y swapped

# flip(pos)

Flip the signs of the position.

Parameters:

• pos : (Position)

Returns:

• Concepts.Position A new position with flipped signs

# flip_x(pos)

Flip the x sign.

Parameters:

• pos : (Position)

Returns:

• Concepts.Position A new position with flipped sign on the x

# flip_y(pos)

Flip the y sign.

Parameters:

• pos : (Position)

Returns:

• Concepts.Position A new position with flipped sign on the y

# lerp(pos1, pos2, alpha)

Lerp position of pos1 and pos2.

Parameters:

• pos1 : (Position)
• pos2 : (Position)
• alpha : (float) 0-1 how close to get to position 2

Returns:

• (Position) the lerped position

# trim(pos, max_len)

Trim the position to a length.

Parameters:

• pos : (Position)
• max_len : (number)

# 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.

# translate(pos, direction, distance)

Translates a position in the given direction.

Parameters:

• pos : (Position) the position to translate
• direction : (defines.direction) the direction of translation
• distance : (number) distance of the translation

Returns:

• (Position) a new translated position

# random(pos[, minimum=0][, maximum=1][, random_tile=false])

Return a random offset of a position.

Parameters:

• pos : (Position) the position to randomize
• minimum : (number) the minimum amount to offset (default: 0)
• maximum : (number) the maximum amount to offset (default: 1)
• random_tile : (boolean) randomize the location on the tile (default: false)

Returns:

• (Position) a new random offset position

# average(positions)

Return the average position of the passed positions.

Parameters:

• positions : (array) array of Concepts.Position

Returns:

• (Position) a new position

# min(positions)

Return the minimum position of the passed positions.

Parameters:

• positions : (array) array of Concepts.Position

Returns:

• (Position) a new position

# max(positions)

Return the maximum position of the passed positions.

Parameters:

• positions : (array) array of Concepts.Position

Returns:

• (Position) a new position

# 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:

• (Position) a new position

# 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:

• (Position) a new position

# intersection(pos1_start, pos1_end, pos2_start, pos2_end)

The intersection of 4 positions.

Parameters:

• pos1_start
• pos1_end
• pos2_start
• pos2_end

Returns:

• (Position) a new position

Position Mutate Methods

# normalized(pos)

Normalizes a position by rounding it to 2 decimal places.

Parameters:

• pos : (Position)

Returns:

• (Position) the normalized position mutated

# absed(pos)

Abs x, y values

Parameters:

• pos : (Position)

Returns:

• (Position) the absolute position mutated

# ceiled(pos)

Ceil x, y values in place.

Parameters:

• pos : (Position)

Returns:

• (Position) the ceiled position mutated

# floored(pos)

Floor x, y values.

Parameters:

• pos : (Position)

Returns:

• (Position) the floored position mutated

# centered(pos)

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

Parameters:

• pos : (Position)

Returns:

• (Position) the centered position mutated

# rounded(pos)

Rounds a positions points to the closest integer.

Parameters:

• pos : (Position)

Returns:

• (Position) the rounded position mutated

# swapped(pos)

Swap the x and y coordinates.

Parameters:

• pos : (Position)

Returns:

• (Position) the swapped position mutated

# flipped(pos)

Flip the signs of the position.

Parameters:

• pos : (Position)

Returns:

• Concepts.Position the flipped position mutated

Position Conversion Methods

# to_pixels(pos)

Convert to pixels from position

Parameters:

• pos : (Position)

Returns:

• (Position) pos

# 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:

• (ChunkPosition) a new chunk position

Usage:

local chunk_x = Position.chunk_position(pos).x

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:

• (BoundingBox) the area

# to_area(pos, width, height)

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

Parameters:

• pos : (Position)
• width : (number)
• height : (number)

Returns:

• (BoundingBox)

# to_tile_area(pos)

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

Parameters:

• pos : (LuaTile.position) the tile position

Returns:

• (BoundingBox) the area of the tile

# to_chunk_area(pos)

Get the chunk area the specified position is in.

Parameters:

• pos : (Position)

Returns:

• (BoundingBox)

# chunk_position_to_chunk_area(pos)

Get the chunk area for the specified chunk position.

Parameters:

• pos : (ChunkPosition)

Returns:

• (BoundingBox) The chunks positions area

Position Functions

# len_squared(pos)

Gets the squared length of a position

Parameters:

• pos : (Position)

Returns:

• (number)

# len(pos)

Gets the length of a position

Parameters:

• pos : (Position)

Returns:

• (number)

# to_string(pos)

Converts a position to a string.

Parameters:

• pos : (Position) the position to convert

Returns:

• (string) string representation of the position

# to_string_xy(pos)

Converts a position to an x, y string.

Parameters:

• pos : (Position) the position to convert

Returns:

• (string)

# to_key(pos)

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

Parameters:

• pos : (Position) the position to convert

Returns:

• (string)

# unpack(pos)

Unpack a position into a tuple.

Parameters:

• pos : (Position) the position to unpack

Returns:

• (tuple) x, y

# pack(pos)

Packs a position into an array.

Parameters:

• pos : (Position) the position to pack

Returns:

• (array)

# is_zero(pos)

Is this position {0, 0}.

Parameters:

• pos : (Position)

Returns:

• (boolean)

# inside(pos, area)

Is a position inside of an area.

Parameters:

• pos : (Position) The pos to check
• area : (BoundingBox) The area to check.

Returns:

• (boolean) Is the position inside of the area.

# is_simple_position(pos)

Is this a simple position.

{num, num}

Parameters:

• pos : (Position)

Returns:

• (boolean)

# is_complex_position(pos)

Is this a complex position.

{x = number, y = number}

Parameters:

• pos : (Position)

Returns:

• (boolean)

# is_Position(pos)

Does the position have the class attached

Parameters:

• pos : (Position)

Returns:

• (boolean)

# is_position(pos)

Is this any position

Parameters:

• pos : (Position)

Returns:

• (boolean)

# atan2(pos1, pos2)

Return the atan2 of 2 positions.

Parameters:

• pos1 : (Position)
• pos2 : (Position)

Returns:

• (number)

# angle(pos1, pos2)

The angle between two positions

Parameters:

• pos1 : (Position)
• pos2 : (Position)

Returns:

• (number)

# cross(pos1, pos2)

Return the cross product of two positions.

Parameters:

• pos1 : (Position)
• pos2 : (Position)

Returns:

• (number)

# equals(pos1, pos2)

Tests whether or not the two given positions are equal.

Parameters:

• pos1 : (Position)
• pos2 : (Position)

Returns:

• (boolean) true if positions are equal

# less_than(pos1, pos2)

Is pos1 less than pos2.

Parameters:

• pos1 : (Position)
• pos2 : (Position)

Returns:

• (boolean)

# less_than_eq(pos1, pos2)

Is pos1 less than or equal to pos2.

Parameters:

• pos1 : (Position)
• pos2 : (Position)

Returns:

• (boolean)

# distance_squared(pos1[, pos2])

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

Parameters:

• pos1 : (Position)
• pos2 : (Position) (optional)

Returns:

• (number) the square of the euclidean distance

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

Calculates the Euclidean distance between two positions.

Parameters:

• pos1 : (Position)
• pos2 : (Position) (default: {x=0)

Returns:

• (number) the euclidean distance

# manhattan_distance(pos1[, pos2])

Calculates the manhatten distance between two positions.

Parameters:

• pos1 : (Position)
• pos2 : (Position) the second position (optional)

Returns:

• (number) the manhatten distance

See also:

• Taxicab geometry (manhatten distance)

# direction_to(pos1, pos2)

Returms the direction to a position using simple delta comparisons.

Parameters:

• pos1 : (Position)
• pos2 : (Position)

Returns:

• (defines.direction)

# complex_direction_to(pos1, pos2, eight_way)

Returns the direction to a position.

Parameters:

• pos1 : (Position)
• pos2 : (Position)
• eight_way : (boolean) return the eight way direction

Returns:

• (defines.direction)

# 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:

• (function) increment_closure a function closure that returns a new incremented position

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:

• (Position) the incremented position

See also:

• increment