A collection of functions for working with points in a 2D coordinate system, along with additional utility functions.

How to use

1. Installation

 npm install pointscape

2. Usage

 import pointscape from "pointscape";

Examples

Most of the functions are designed for working with points in a 2D coordinate system.

 import { 
    distance,
    middle,
    angle,
    center,
    perimeter
    } from "pointscape";
 import type { Point } from "pointscape";  
 
 // Working with points

 const point1: Point = {x: 0, y: 0}, point2: Point = {x: 10, y: 10};


 const distanceBetweenPoints = distance(point1, point2); 
 // result: 14.142135623730951


 const middlePoint = middle(point1, point2);
 // result: {x: 5, y: 5}


 const angleBetweenPoints = angle(point1, point2);
 // result: 0.7853981633974483
 

 const point3: Point = {x:0, y:10}, point4: Point = {x:10, y:0};

 const perimeterOfPoints = perimeter(
   [point1, point2, point3, point4 ]
 );
 // result: 48.2842712474619

The Point class can also be used for working with the points.

 import { Point } from "pointscape";

 const point1 = new Point(0, 0);
 const point2 = new Point(1, 1);

 const distance = point1.distanceTo(point2);
 // result:  1.4142135623730951

 const angle = point1.angleTo(point2);
 // result:  0.7853981633974483
 

There are other utility functions as well.

 import { 
    inRange,
    chunk, 
    randomBoolean } from "pointscape";

 //  Helper functions for math 

 const isInTheRange = inRange(1, 0, 10);
 // result: true


 // Helper functions for arrays 

 const chunks = chunk([1, 1, 1, 1], 2);
 // result: [[1, 1], [1, 1]]


 // Helper functions for randomization 

 const randomBool = randomBoolean();
 // result: true or false

The list of available functions

Categories

• Points
  • Geometry
  • Positioning
  • Relationships
• Math
• Arrays
• Randomization

Points

Positioning

distance

positionInCircle

angle

nearest

farest

randomPoint

randomPointInDistance

randomPoints

rotate

inLine

cross

move

Geometry

area

middle

center

perimeter

square

rectangle

pentagon

triangle

circleArea

Relationships

collision

collisionInArray

possibleConnections

pointWithoutCollision

sort

scale

Math

degreesToRadians

radiansToDegrees

inRange

roundToPrecision

average

Arrays

intersection

difference

chunk

removeDuplicate

sample

Randomization

randomNumber

randomBoolean

uniqueId

Documentation for the functions

Points

Positioning

• distance

  interface Point {
    x: number
    y: number
  }

  (point1: Point, point2: Point) => number

Returns the distance beetween two points, each point is an object with x and y properties.

• positionInCircle

  (point: Point, radius: number, angleInRadians: number) => Point

Returns the x and y coordinates for the current point in the circle, given its center point, radius, and angle.

• angle

  (point1: Point, point2: Point) => number

Returns the angle formed by the connection of two points.

• nearest

  (point: Point, points: Point[]) => Point

Returns the nearest point to the given point from the array.

• farest

  (point: Point, points: Point[]) => Point

Returns the farest point to the given point from the array.

• randomPoint

  ([xBounds]: Bounds, [yBounds]: Bounds) => Point

Returns a random point within the given dimensions, if provided, otherwise in 100 units on both axes.

• randomPointInDistance

  (point: Point, distance: number) => Point

Returns a random point within the given distance from the specified point.

• randomPoints

   ([xBounds]: Bounds, [yBounds]: Bounds, quantity: number,) => Point[]

Returns a specified quantity of random points within the given dimensions, if dimensions are provided, otherwise in the range of 100.

• rotate

  (point: Point, points: Point[], angleInRadians: number) => Point[]

Returns the points rotated around the given point.

• inLine

  interface Line {
    start: Point
    end: Point
  }

  (point: Point, line: Line) => boolean

Returns boolean value indicating whether or not the given coordinates are on line defined by two other points.

• cross

 (line1: Line, line2: Line) => boolean

Returns boolean value indicating if two lines each defined by two points intersect.

• move

 (point: Point, xStep: number, yStep: number) => Point

Returns a point of with the new coordinates.

Geometry

• area

  (points: Point[]) => number

Returns the area enclosed by the given points. Takes an array of points as argument, where each point is an object with x and y properties.

• middle

  (point1: Point, point2: Point) => Point

Returns the midpoint between two points.

• center

  (points: Point[]) => Point

Returns the center of the given points.

• perimeter

  (points: Point[]) => number

Returns the perimeter of the figure formed by the given points.

• square

 (point: Point, size: number, [direction]: "left" | "right" | "down" | "up" ) => Point[]

Returns an array of points representing a shape of square.Takes four parameters: starting coordinates (x and y), size of square side, and direction which should be one of the values "left", "right", "up", "down".

• rectangle(point, size, [direction])

 (point: Point, size: number, [direction]: "left" | "right" | "down" | "up" ) => Point[]

Returns an array of points representing a shape of rectangle.Takes same parameters as square function.

• pentagon(point, size, [direction])

 (point: Point, size: number, [direction]: "left" | "right" | "down" | "up" ) => Point[]

Returns an array of points representing a shape of pentagon.Takes four parameters: starting coordinates (x and y), size of pentagon side, and the angle of pentagon's rotation.

• triangle(point, size, [direction])

 (point: Point, size: number, [direction]: "left" | "right" | "down" | "up" ) => Point[]

Returns an array of points representing a shape of triangle.Takes same parameters as square function.

• circleArea

  (radius): number => number

Returns the area of the circle.

Relationships

• collision

  (point1: Point, point2: Point, collisionDistance: number, [callback]: Function) => boolean

Returns a boolean indicating if the two points are closer than the given distance.

• collisionInArray

  (point: Point, radius: number, points: Point[], [callback]: Function) => Point[]

Returns the points that are closer than the radius to the given point.

• possibleConnections

  (pointsCount: number) => number

Returns the quantity of possible connections among given quantity of points.

• pointWithoutCollision(minX, maxX, minY, maxY, distance, points)

  interface Bounds {
    min: number
    max: number
  }

  (xBounds: Bounds, yBounds: Bounds, distance: number, points: Point[]) => Point | string

Returns a point that doesn't collide with any of the given points within the specified distance, if such a point exists, otherwise returns error string.

• sort

  (points: Point, [coordinate]: "x" | "y") => Point[]

Returns sorted array of the points.The coordinate parameter can be "x", "y", or none for sorting both for "x" and "y".

• scale

  (scaleFactorX: number, scaleFactorY: number, points: Point[]) => Point[]

Returns the scaled points.

Math

• degreesToRadians

 (degrees: number) => number

Converts degrees to radians.

• radiansToDegrees

 (radians: number) => number

Converts radians to degrees.

• inRange

 (number: number, min: number, max: number) => boolean

Returns true if the given number is within the specified range.

• roundToPrecision)

 (number: number, precision: -100 | -10 | 0 | 10 | 100 | number) => number

Rounds the number to the given precision.

• average

 (numbers: number[]) => number

Returns the average of all numbers in an array.

Arrays

• intersection(

 (arr1: any[], arr2: any[]) => any[]

Returns the array of intersection of two arrays.

• difference

 (arr1: any[], arr2: any[]) => any[]

Returns the array of difference of two arrays.

• chunk

 (arr: any[], perArr: number) => any[][]

Returns an array splited into chunks based on elements count per chunk.

• removeDuplicates(arr)

 (arr: any[]) => any[]

Returns the array without duplicates.

• sample

  (arr: any[], [size]: number[]) => any[]

Returns a random sample from an array with optional size argument for sampling length. If not specified, it returns only one element.

Randomization

• randomNumber

  (min: number, max: number) => number

Returns a random number within the given range.

• randomBoolean

  () => boolean

Returns a random boolean value.

• uniqueId

  ([other ids]: string[]) => string 

Returns a unique ID that's different from the provided IDs, or a random ID if no other IDs are given.