https://github.com/arman2409/pointscape
NPM package of utility functions for working with points in 2D coordinate system
https://github.com/arman2409/pointscape
2d canvas collision-detection distance npm-package points xy
Last synced: 4 months ago
JSON representation
NPM package of utility functions for working with points in 2D coordinate system
- Host: GitHub
- URL: https://github.com/arman2409/pointscape
- Owner: Arman2409
- License: mit
- Created: 2024-01-08T18:12:40.000Z (over 2 years ago)
- Default Branch: develop
- Last Pushed: 2026-01-16T12:48:33.000Z (5 months ago)
- Last Synced: 2026-01-17T03:22:07.728Z (5 months ago)
- Topics: 2d, canvas, collision-detection, distance, npm-package, points, xy
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/pointscape
- Size: 120 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
**A collection of functions for working with points in a 2D coordinate system, along with additional utility functions.**
## How to use
1. Installation
```bash
npm install pointscape
```
2. Usage
```typescript
import pointscape from "pointscape";
```
## Examples
Most of the functions are designed for working with points in a 2D coordinate system.
```typescript
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.
```typescript
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.
```typescript
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](#points)
- [Geometry](#geometry)
- [Positioning](#positioning)
- [Relationships](#relationships)
- [Math](#math)
- [Arrays](#arrays)
- [Randomization](#randomization)
#### Points
##### Positioning
[distance](#distance)
[positionInCircle](#positionincircle)
[angle](#angle)
[nearest](#nearest)
[farest](#farest)
[randomPoint](#randompoint)
[randomPointInDistance](#randompointindistance)
[randomPoints](#randompoints)
[rotate](#rotate)
[inLine](#inline)
[cross](#cross)
[move](#move)
##### Geometry
[area](#area)
[middle](#middle)
[center](#center)
[perimeter](#perimeter)
[square](#square)
[rectangle](#rectangle)
[pentagon](#pentagon)
[triangle](#triangle)
[circleArea](#circlearea)
##### Relationships
[collision](#collision)
[collisionInArray](#collisioninarray)
[possibleConnections](#possibleconnections)
[pointWithoutCollision](#pointwithoutcollision)
[sort](#sort)
[scale](#scale)
#### Math
[degreesToRadians](#degreestodadians)
[radiansToDegrees](#radianstodegrees)
[inRange](#inrange)
[roundToPrecision](#roundtoprecision)
[average](#average)
#### Arrays
[intersection](#intersection)
[difference](#difference)
[chunk](#chunk)
[removeDuplicate](#removeDuplicates)
[sample](#sample)
#### Randomization
[randomNumber](#randomnumber)
[randomBoolean](#randomboolean)
[uniqueId](#uniqueid)
## Documentation for the functions
### Points
##### Positioning
* distance
```typescript
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
```typescript
(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
```typescript
(point1: Point, point2: Point) => number
```
Returns the angle formed by the connection of two points.
* nearest
```typescript
(point: Point, points: Point[]) => Point
```
Returns the nearest point to the given point from the array.
* farest
```typescript
(point: Point, points: Point[]) => Point
```
Returns the farest point to the given point from the array.
* randomPoint
```typescript
([xBounds]: Bounds, [yBounds]: Bounds) => Point
```
Returns a random point within the given dimensions, if provided, otherwise in 100 units on both axes.
* randomPointInDistance
```typescript
(point: Point, distance: number) => Point
```
Returns a random point within the given distance from the specified point.
* randomPoints
```typescript
([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
```typescript
(point: Point, points: Point[], angleInRadians: number) => Point[]
```
Returns the points rotated around the given point.
* inLine
```typescript
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
```typescript
(line1: Line, line2: Line) => boolean
```
Returns boolean value indicating if two lines each defined by two points intersect.
* move
```typescript
(point: Point, xStep: number, yStep: number) => Point
```
Returns a point of with the new coordinates.
##### Geometry
* area
```typescript
(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
```typescript
(point1: Point, point2: Point) => Point
```
Returns the midpoint between two points.
* center
```typescript
(points: Point[]) => Point
```
Returns the center of the given points.
* perimeter
```typescript
(points: Point[]) => number
```
Returns the perimeter of the figure formed by the given points.
* square
```typescript
(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])
```typescript
(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](#square) function.
* pentagon(point, size, [direction])
```typescript
(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])
```typescript
(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](#square) function.
* circleArea
```typescript
(radius): number => number
```
Returns the area of the circle.
##### Relationships
* collision
```typescript
(point1: Point, point2: Point, collisionDistance: number, [callback]: Function) => boolean
```
Returns a boolean indicating if the two points are closer than the given distance.
* collisionInArray
```typescript
(point: Point, radius: number, points: Point[], [callback]: Function) => Point[]
```
Returns the points that are closer than the radius to the given point.
* possibleConnections
```typescript
(pointsCount: number) => number
```
Returns the quantity of possible connections among given quantity of points.
* pointWithoutCollision(minX, maxX, minY, maxY, distance, points)
```typescript
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
```typescript
(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
```typescript
(scaleFactorX: number, scaleFactorY: number, points: Point[]) => Point[]
```
Returns the scaled points.
### Math
* degreesToRadians
```typescript
(degrees: number) => number
```
Converts degrees to radians.
* radiansToDegrees
```typescript
(radians: number) => number
```
Converts radians to degrees.
* inRange
```typescript
(number: number, min: number, max: number) => boolean
```
Returns true if the given number is within the specified range.
* roundToPrecision)
```typescript
(number: number, precision: -100 | -10 | 0 | 10 | 100 | number) => number
```
Rounds the number to the given precision.
* average
```typescript
(numbers: number[]) => number
```
Returns the average of all numbers in an array.
### Arrays
* intersection(
```typescript
(arr1: any[], arr2: any[]) => any[]
```
Returns the array of intersection of two arrays.
* difference
```typescript
(arr1: any[], arr2: any[]) => any[]
```
Returns the array of difference of two arrays.
* chunk
```typescript
(arr: any[], perArr: number) => any[][]
```
Returns an array splited into chunks based on elements count per chunk.
* removeDuplicates(arr)
```typescript
(arr: any[]) => any[]
```
Returns the array without duplicates.
* sample
```typescript
(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
```typescript
(min: number, max: number) => number
```
Returns a random number within the given range.
* randomBoolean
```typescript
() => boolean
```
Returns a random boolean value.
* uniqueId
```typescript
([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.