Area.Area module

Tools for working with bounding boxes.

See also

Usage

local Area = require('__stdlib__/stdlib/area/area')

Constructor Methods

construct([x1=0][, y1=0][, x2=0][, y2=0]) Creates an area from number parameters.
from_key(area_string) Converts a string key area to an area.
from_string(area_string) Converts an area string to an area.
new(area, copy) Converts an area in either array or table format to an area with a metatable.
set(area) Loads the metatable into the passed Area without creating a new one.

Area Methods

adjust(area, amount) Adjust an area by shrinking or expanding.
ceil(area) Ceils an area by increasing the size of the area outwards
center_points(area) Gets the center positions of the tiles where the given area’s two positions reside.
corners(area) add left_bottom and right_top to the area
expand(area, amount) Expands the area outwards by the given amount.
flip(area) Flip an area such that its value of the width becomes the height, and its value of the height becomes the width.
floor(area) Floors an area by decreasing the size of the area inwards.
from_pixels(area) Convert area from pixels.
non_zero(area, amount) Return a non zero sized area by expanding if needed
normalize(area) Normalizes the given area.
offset(area, pos) Offsets the area by the {x, y} values.
recall(area) Recalls the stored area.
round(area) Rounds an areas points to its closest integer.
shrink(area, amount) Shrinks the area inwards by the given amount.
shrink_to_surface_size(area, surface) Shrinks an area to the size of the surface if it is bigger
store(area) Stores the area for recall later, not deterministic.
to_diameter(area, diameter) Returns the area to the diameter from top_left
to_pixels(area) Convert area to pixels.
to_surface_size(area, surface) Set an area to the whole size of the surface.
translate(area, direction, distance) Translates an area in the given direction.

Position Conversion Functions

center(area) Calculates the center of the area and returns the position.

Area Functions

collides(area1, area2) Does either area overlap/collide with the other area.
collides_areas(area, areas) Do all passed areas collide with an area.
contains_areas(area, areas) Are all passed areas completly inside an area.
contains_positions(area, positions) Are the passed positions all located in an area.
equals(area1, area2) Returns true if two areas are the same.
is_set(area) Does the area have the class attached
is_zero(area) Is this a non zero sized area
less_than(area1, area2) Is area1 smaller in size than area2
normalized(area) Is the area normalized.
pack(area) Pack an area into an array.
pack_positions(area) Pack an area into a simple bounding box array
size(area) Gets the properties of the given area.
to_key(area) Return a suitable string for using as a table key
to_string(area) Converts an area to a string.
unpack(area) Unpack an area into a tuple.
unpack_positions(area) Unpack an area into a tuple of position tables.
valid(area) Is the area non-zero and normalized.

Area Iterators

Metamethods Area tables are returned with these Metamethods attached.
iterate(area) Iterates an area.
spiral_iterate(area) Iterates the given area in a spiral as depicted below, from innermost to the outermost location.

Constructor Methods

# construct([x1=0][, y1=0][, x2=0][, y2=0])

Creates an area from number parameters.

Parameters:
  • x1 : (number) x-position of left_top, first position (default: 0)
  • y1 : (number) y-position of left_top, first position (default: 0)
  • x2 : (number) x-position of right_bottom, second position (default: 0)
  • y2 : (number) y-position of right_bottom, second position (default: 0)
Returns:
# from_key(area_string)

Converts a string key area to an area.

Parameters:
  • area_string : (string) the area to convert
Returns:
# from_string(area_string)

Converts an area string to an area.

Parameters:
  • area_string : (string) the area to convert
Returns:
# new(area, copy)

Converts an area in either array or table format to an area with a metatable.

Returns itself if it already has a metatable

Parameters: Returns:
# set(area)

Loads the metatable into the passed Area without creating a new one.

Parameters:
  • area : (BoundingBox) the Area to set the metatable onto
Returns:

Area Methods

# adjust(area, amount)

Adjust an area by shrinking or expanding.

Imagine pinching & holding with fingers the top-left & bottom-right corners of a 2D box and pulling outwards to expand and pushing inwards to shrink the box.

Parameters: Returns: Usage:
local area = Area.adjust({{-2, -2}, {2, 2}}, {4, -1})
 -- returns {left_top = {x = -6, y = -1}, right_bottom = {x = 6, y = 1}}
# ceil(area)

Ceils an area by increasing the size of the area outwards

Parameters: Returns:
# center_points(area)

Gets the center positions of the tiles where the given area’s two positions reside.

Parameters: Returns:
  • (BoundingBox) the area with its two positions at the center of the tiles in which they reside
# corners(area)

add left_bottom and right_top to the area

Parameters: Returns:
  • (BoundingBox) the area with left_bottom and right_top included
# expand(area, amount)

Expands the area outwards by the given amount.

Parameters: Returns: See also:
# flip(area)

Flip an area such that its value of the width becomes the height, and its value of the height becomes the width.

Parameters: Returns:
# floor(area)

Floors an area by decreasing the size of the area inwards.

Parameters: Returns:
# from_pixels(area)

Convert area from pixels.

Parameters: Returns:
# non_zero(area, amount)

Return a non zero sized area by expanding if needed

Parameters: Returns:
# normalize(area)

Normalizes the given area.

  • Swaps the values between right_bottom.x & left_top.x IF right_bottom.x < left_top.x
  • Swaps the values between right_bottom.y & left_top.y IF right_bottom.y < left_top.y

Parameters: Returns:
# offset(area, pos)

Offsets the area by the {x, y} values.

Parameters:
  • area : (BoundingBox) the area to offset
  • pos : (Position) the position to which the area will offset
Returns:
# recall(area)

Recalls the stored area.

Parameters: Returns:
# round(area)

Rounds an areas points to its closest integer.

Parameters: Returns:
# shrink(area, amount)

Shrinks the area inwards by the given amount.

The area shrinks inwards from top-left towards the bottom-right, and from bottom-right towards the top-left.

Parameters: Returns:
# shrink_to_surface_size(area, surface)

Shrinks an area to the size of the surface if it is bigger

Parameters:
  • area
  • surface
# store(area)

Stores the area for recall later, not deterministic.

Only the last area stored is saved.

Parameters:
# to_diameter(area, diameter)

Returns the area to the diameter from top_left

Parameters: Returns:
# to_pixels(area)

Convert area to pixels.

Parameters: Returns:
# to_surface_size(area, surface)

Set an area to the whole size of the surface.

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

Translates an area in the given direction.

Parameters: Returns:

Position Conversion Functions

# center(area)

Calculates the center of the area and returns the position.

Parameters: Returns:

Area Functions

# collides(area1, area2)

Does either area overlap/collide with the other area.

Parameters: Returns:
# collides_areas(area, areas)

Do all passed areas collide with an area.

Parameters: Returns:
# contains_areas(area, areas)

Are all passed areas completly inside an area.

Parameters: Returns:
# contains_positions(area, positions)

Are the passed positions all located in an area.

Parameters:
  • area : (BoundingBox) the search area
  • positions : (array) array of Concepts.Position
Returns:
  • (boolean) true if the positions are located in the area
# equals(area1, area2)

Returns true if two areas are the same.

Parameters: Returns:
  • (boolean) true if areas are the same
# is_set(area)

Does the area have the class attached

Parameters: Returns:
# is_zero(area)

Is this a non zero sized area

Parameters: Returns:
# less_than(area1, area2)

Is area1 smaller in size than area2

Parameters: Returns:
  • (boolean) is area1 less than area2 in size
# normalized(area)

Is the area normalized.

Parameters: Returns:
# pack(area)

Pack an area into an array.

Parameters: Returns:
# pack_positions(area)

Pack an area into a simple bounding box array

Parameters: Returns:
# size(area)

Gets the properties of the given area.

This function returns a total of four values that represent the properties of the given area.

Parameters:
  • area : (BoundingBox) the area from which to get the size
Returns:
  • (number) the size of the area — (width × height)
  • (number) the width of the area
  • (number) the height of the area
  • (number) the perimeter of the area — (2 × (width + height))
# to_key(area)

Return a suitable string for using as a table key

Parameters: Returns:
  • string
# to_string(area)

Converts an area to a string.

Parameters: Returns:
  • (string) the string representation of the area
# unpack(area)

Unpack an area into a tuple.

Parameters: Returns:
  • (tuple) lt.x, lt.y, rb.x, rb.y
# unpack_positions(area)

Unpack an area into a tuple of position tables.

Parameters: Returns:
  • (tuple) left_top, right_bottom
# valid(area)

Is the area non-zero and normalized.

Parameters: Returns:

Area Iterators

# Metamethods

Area tables are returned with these Metamethods attached.

Fields:
  • __class
  • __index : If key is not found see if there is one available in the Area module.
  • __tostring : Will print a string representation of the area.
  • __concat : calls tostring on both sides of concat.
  • __add : Will adjust if RHS is vector/position, add offset if RHS is number/area
  • __sub : Will adjust if RHS is vector/position, sub offset if RHS is number/area
  • __mul
  • __div
  • __mod
  • __unm
  • __eq : Is area1 the same as area2.
  • __lt : is the size of area1 less than number/area2.
  • __le : is the size of area1 less than or equal to number/area2.
  • __len : The size of the area.
  • __call : Return a new copy
# iterate(area)

Iterates an area.

Parameters: Returns: Usage:
for x,y in Area.iterate({{0, -5}, {3, -3}}) do
...
end
# spiral_iterate(area)

Iterates the given area in a spiral as depicted below, from innermost to the outermost location.

Parameters:
  • area : (BoundingBox) the area on which to perform a spiral iteration
Returns: Usage:
for x, y in Area.spiral_iterate({{-2, -1}, {2, 1}}) do
print('(' .. x .. ', ' .. y .. ')')
end
prints: (0, 0) (1, 0) (1, 1) (0, 1) (-1, 1) (-1, 0) (-1, -1) (0, -1) (1, -1) (2, -1) (2, 0) (2, 1) (-2, 1) (-2, 0) (-2, -1)