docs » hs.geometry

Utility object to represent points, sizes and rects in a bidimensional plane

An hs.geometry object can be:

You can create these objects in many different ways, via my_obj=hs.geometry.new(...) or simply my_obj=hs.geometry(...) by passing any of the following:

You can use any of these anywhere an hs.geometry object is expected in Hammerspoon; the constructor will be called for you.

API Overview

API Documentation

Constructors

copy
Signature hs.geometry.copy(geom) -> hs.geometry object
Type Constructor
Description

Creates a copy of an hs.geometry object

Parameters:

  • geom - an hs.geometry object to copy

Returns:

  • a newly created copy of the hs.geometry object
new
Signature hs.geometry.new(...) -> hs.geometry object
Type Constructor
Description

Creates a new hs.geometry object

Parameters: see the module description at the top

Returns:

  • a newly created hs.geometry object
point
Signature hs.geometry.point(x, y) -> hs.geometry point
Type Constructor
Description

Convenience function for creating a point object

Parameters:

  • x - A number containing the horizontal co-ordinate of the point
  • y - A number containing the vertical co-ordinate of the point

Returns:

  • An hs.geometry point object
rect
Signature hs.geometry.rect(x, y, w, h) -> hs.geometry rect
Type Constructor
Description

Convenience function for creating a rect-table

Parameters:

  • x - A number containing the horizontal co-ordinate of the top-left point of the rect
  • y - A number containing the vertical co-ordinate of the top-left point of the rect
  • w - A number containing the width of the rect
  • h - A number containing the height of the rect

Returns:

  • An hs.geometry rect object
size
Signature hs.geometry.size(w, h) -> hs.geometry size
Type Constructor
Description

Convenience function for creating a size object

Parameters:

  • w - A number containing a width
  • h - A number containing a height

Returns:

  • An hs.geometry size object

Fields

area
Signature hs.geometry.area
Type Field
Description

A number representing the area of this rect or size; changing it will scale the rect/size - see hs.geometry:scale()
aspect
Signature hs.geometry.aspect
Type Field
Description

A number representing the aspect ratio of this rect or size; changing it will reshape the rect/size, keeping its area and center constant
bottomright
Signature hs.geometry.bottomright
Type Field
Description

Alias for x2y2
center
Signature hs.geometry.center
Type Field
Description

A point representing the geometric center of this rect or the midpoint of this vector2; changing it will move the rect/vector accordingly
h
Signature hs.geometry.h
Type Field
Description

The height of this rect or size; changing it will keep the rect's x,y corner constant
length
Signature hs.geometry.length
Type Field
Description

A number representing the length of the diagonal of this rect, or the length of this vector2; changing it will scale the rect/vector - see hs.geometry:scale()
string
Signature hs.geometry.string
Type Field
Description

The "X,Y/WxH" string for this hs.geometry object (reduced precision); useful e.g. for logging
table
Signature hs.geometry.table
Type Field
Description

The {x=X,y=Y,w=W,h=H} table for this hs.geometry object; useful e.g. for serialization/deserialization
topleft
Signature hs.geometry.topleft
Type Field
Description

Alias for xy
w
Signature hs.geometry.w
Type Field
Description

The width of this rect or size; changing it will keep the rect's x,y corner constant
wh
Signature hs.geometry.wh
Type Field
Description

The size component for this hs.geometry object; setting this to a new size will keep the rect's x,y corner constant
x
Signature hs.geometry.x
Type Field
Description

The x coordinate for this point or rect's corner; changing it will move the rect but keep the same width and height
x1
Signature hs.geometry.x1
Type Field
Description

Alias for x
x2
Signature hs.geometry.x2
Type Field
Description

The x coordinate for the second corner of this rect; changing it will affect the rect's width
x2y2
Signature hs.geometry.x2y2
Type Field
Description

The point denoting the other corner of this hs.geometry object; setting this to a new point will change the rect's width and height
xy
Signature hs.geometry.xy
Type Field
Description

The point component for this hs.geometry object; setting this to a new point will move the rect but keep the same width and height
y
Signature hs.geometry.y
Type Field
Description

The y coordinate for this point or rect's corner; changing it will move the rect but keep the same width and height
y1
Signature hs.geometry.y1
Type Field
Description

Alias for y
y2
Signature hs.geometry.y2
Type Field
Description

The y coordinate for the second corner of this rect; changing it will affect the rect's height

Methods

angle
Signature hs.geometry:angle() -> number
Type Method
Description

Returns the angle between the positive x axis and this vector2

Parameters:

  • None

Returns:

  • a number represeting the angle in radians
angleTo
Signature hs.geometry:angleTo(point) -> number
Type Method
Description

Returns the angle between the positive x axis and the vector connecting this point or rect's center to another point or rect's center

Parameters:

  • point - an hs.geometry object, or a table or string or parameter list to construct one; if a rect, uses the rect's center

Returns:

  • a number represeting the angle in radians
distance
Signature hs.geometry:distance(point) -> number
Type Method
Description

Finds the distance between this point or rect's center and another point or rect's center

Parameters:

  • point - an hs.geometry object, or a table or string or parameter list to construct one; if a rect, uses the rect's center

Returns:

  • a number indicating the distance
equals
Signature hs.geometry:equals(other) -> boolean
Type Method
Description

Checks if two geometry objects are equal

Parameters:

  • other - another hs.geometry object, or a table or string or parameter list to construct one

Returns:

  • true if this hs.geometry object perfectly overlaps other, false otherwise
fit
Signature hs.geometry:fit(bounds) -> hs.geometry object
Type Method
Description

Ensure this rect is fully inside bounds, by scaling it down if it's larger (preserving its aspect ratio) and moving it if necessary

Parameters:

  • bounds - an hs.geometry rect object, or a table or string or parameter list to construct one, indicating the rect that must fully contain this rect

Returns:

  • this hs.geometry object for method chaining
floor
Signature hs.geometry:floor() -> hs.geometry object
Type Method
Description

Truncates all coordinates in this object to integers

Parameters:

  • None

Returns:

  • this hs.geometry point for method chaining
fromUnitRect
Signature hs.geometry:fromUnitRect(frame) -> hs.geometry rect
Type Method
Description

Converts a unit rect within a given frame into a rect

Parameters:

  • frame - an hs.geometry rect (with w and h >0)

Returns:

  • An hs.geometry rect object
inside
Signature hs.geometry:inside(rect) -> boolean
Type Method
Description

Checks if this hs.geometry object lies fully inside a given rect

Parameters:

  • rect - an hs.geometry rect, or a table or string or parameter list to construct one

Returns:

  • true if this point/rect lies fully inside the given rect, false otherwise
intersect
Signature hs.geometry:intersect(rect) -> hs.geometry rect
Type Method
Description

Returns the intersection rect between this rect and another rect

Parameters:

  • rect - an hs.geometry rect, or a table or string or parameter list to construct one

Returns:

  • a new hs.geometry rect

Notes:

  • If the two rects don't intersect, the result rect will be a "projection" of the second rect onto this rect's closest edge or corner along the x or y axis; the w and/or h fields in the result rect will be 0.
move
Signature hs.geometry:move(point) -> hs.geometry object
Type Method
Description

Moves this point/rect

Parameters:

  • point - an hs.geometry object, or a table or string or parameter list to construct one, indicating the x and y displacement to apply

Returns:

  • this hs.geometry object for method chaining
normalize
Signature hs.geometry:normalize() -> point
Type Method
Description

Normalizes this vector2

Parameters:

  • None

Returns:

  • this hs.geometry point for method chaining
rotateCCW
Signature hs.geometry:rotateCCW(aroundpoint, ntimes) -> hs.geometry point
Type Method
Description

Rotates a point around another point N times

Parameters:

  • aroundpoint - an hs.geometry point to rotate this point around
  • ntimes - the number of times to rotate, defaults to 1

Returns:

  • A new hs.geometry point containing the location of the rotated point
scale
Signature hs.geometry:scale(size) -> hs.geometry object
Type Method
Description

Scales this vector2/size, or this rect keeping its center constant

Parameters:

  • size - an hs.geometry object, or a table or string or parameter list to construct one, indicating the factors for scaling this rect's width and height; if a number, the rect will be scaled by the same factor in both axes

Returns:

  • this hs.geometry object for method chaining
toUnitRect
Signature hs.geometry:toUnitRect(frame) -> hs.geometry unit rect
Type Method
Description

Converts a rect into its unit rect within a given frame

Parameters:

  • frame - an hs.geometry rect (with w and h >0)

Returns:

  • An hs.geometry unit rect object

Notes:

  • The resulting unit rect is always clipped within frame's bounds (via hs.geometry:intersect()); if frame does not encompass this rect no error will be thrown, but the resulting unit rect won't be a direct match with this rect (i.e. calling :fromUnitRect(frame) on it will return a different rect)
type
Signature hs.geometry:type() -> string
Type Method
Description

Returns the type of an hs.geometry object

Parameters:

  • None

Returns:

  • a string describing the type of this hs.geometry object, i.e. 'point', 'size', 'rect' or 'unitrect'; nil if not a valid object
union
Signature hs.geometry:union(rect) -> hs.geometry rect
Type Method
Description

Returns the smallest rect that encloses both this rect and another rect

Parameters:

  • rect - an hs.geometry rect, or a table or string or parameter list to construct one

Returns:

  • a new hs.geometry rect
vector
Signature hs.geometry:vector(point) -> point
Type Method
Description

Returns the vector2 from this point or rect's center to another point or rect's center

Parameters:

  • point - an hs.geometry object, or a table or string or parameter list to construct one; if a rect, uses the rect's center

Returns:

  • an hs.geometry point