# geometry

Utility object to represent points, sizes and rects in a bidimensional plane
An hs.geometry object can be:
• a point, or vector2, with `x` and `y` fields for its coordinates
• a size with `w` and `h` fields for width and height respectively
• a rect, which has both a point component for one of its corners, and a size component - so it has all 4 fields
• a unit rect, which is a rect with all fields between 0 and 1; it represents a "relative" rect within another (absolute) rect (e.g. a unit rect `x=0,y=0 , w=0.5,h=0.5` is the quarter portion closest to the origin); please note that hs.geometry makes no distinction internally between regular rects and unit rects; you can convert to and from as needed via the appropriate methods
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:
• 4 parameters `X,Y,W,H` for the respective fields - W and H, or X and Y, can be `nil`:
• `hs.geometry(X,Y)` creates a point
• `hs.geometry(nil,nil,W,H)` creates a size
• `hs.geometry(X,Y,W,H)` creates a rect given its width and height from a corner
• a table `{X,Y}` creates a point
• a table `{X,Y,W,H}` creates a rect
• a table `{x=X,y=Y,w=W,h=H}` creates a rect, or if you omit X and Y, or W and H, creates a size or a point respectively
• a table `{x1=X1,y1=Y1,x2=X2,y2=Y2}` creates a rect, where X1,Y1 and X2,Y2 are the coordinates of opposite corners
• a string:
• `"X Y"` or `"X,Y"` creates a point
• `"WxH"` or `"W*H"` creates a size
• `"X Y/WxH"` or `"X,Y W*H"` (or variations thereof) creates a rect given its width and height from a corner
• `"X1,Y1>X2,Y2"` or `"X1 Y1 X2 Y2"` (or variations thereof) creates a rect given two opposite corners
• `"[X,Y WxH]"` or `"[X1,Y1 X2,Y2]"` or variations (note the square brackets) creates a unit rect where x=X/100, y=Y/100, w=W/100, h=H/100
• a point and a size `"X Y","WxH"` or `{x=X,y=Y},{w=W,h=H}` create a rect
You can use any of these anywhere an hs.geometry object is expected in Hammerspoon; the constructor will be called for you.

## 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 pointy - 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 recty - A number containing the vertical co-ordinate of the top-left point of the rectw - A number containing the width of the recth - 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 widthh - 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`