Points

A specification for storing shape data in Javascript. Includes functions for adding, removing, reordering, converting and manipulating points.

3.1kb gzipped. No dependencies.

Example shape

const shape = [
  { x: 50, y: 30, moveTo: true },
  { x: 50, y: 70, curve: { type: 'arc', rx: 20, ry: 20 }},
  { x: 50, y: 30, curve: { type: 'arc', rx: 20, ry: 20 }},
];

Specification

A shape is an array of 2 or more point objects.

A line should be drawn between each point in a shape.

Adding a moveTo property to a point indicates that a line should not be drawn to that point from the previous.

The first point in a shape must include the moveTo property.

Point types

Each point is somewhere on an x, y plane. Therefore, at the very least each point object requires x and y properties. Values should be numeric.

Basic

{ x: 10, y: 25 }

Arc

{ x: 80, y: 35, curve: {
  type: 'arc',
  rx: 2,
  ry: 2,
  xAxisRotation: 45,
  sweepFlag: 1,
  largeArcFlag: 1,
}}

The curve properties xAxisRotation, sweepFlag and largeArcFlag are all optional and if missing are assumed to be 0.

Quadratic bezier

{ x: 100, y: 200, curve: {
  type: 'quadratic',
  x1: 50,
  y1: 200,
}}

Cubic bezier

{ x: 5, y: 10, curve: {
  type: 'cubic',
  x1: 2,
  y1: 0,
  x2: 3,
  y2: 10,
}}

Installation

npm install points

Usage

add

import { add } from 'points';
const newShape = add( shape, 25 );

Takes an existing shape array as the first argument, and the total number of desired points as the second argument. Adds points without changing the shape and returns a new shape array.

boundingBox

import { boundingBox } from 'points';
const { top, right, bottom, left, center } = boundingBox( shape );

Takes an existing shape array, or an array of shape arrays, as the only argument and returns an object of bounding coordinates including a center property containing the x, y values.

cubify

import { cubify } from 'points';
const newShape = cubify( shape );

Takes an existing shape array as the only argument, or an array of shape arrays, and converts any arc or quadratic bezier points to cubic bezier points.

Returns a new shape array or an array of shape arrays, depending on input.

moveIndex

import { moveIndex } from 'points';
const newShape = moveIndex( shape, 3 );

Takes an existing shape array as the first argument, and the desired number of points to shift the index as the second argument (this can be a negative integer too). Returns a new shape array.

offset

import { offset } from 'points';
const newShape = offset( shape, 10, 20 );

Takes an existing shape array as the first argument, the horizontal offset as the second argument, and the vertical offset as the third argument. Returns a new shape array.

remove

import { remove } from 'points';
const newShape = remove( shape );

Takes an existing shape array, or an array of shape arrays, as the only argument, and removes any points that do not affect the shape.

Returns a new shape array or an array of shape arrays, depending on input.

reverse

import { reverse } from 'points';
const newShape = reverse( shape );

Takes an existing shape array, or an array of shape arrays, as the only argument, and reverses the order of the points.

Returns a new shape array or an array of shape arrays, depending on input.

scale

import { scale } from 'points';
const newShape = scale( shape, 0.5, 'topLeft' );

Takes an existing shape array, or an array of shape arrays, as the first argument. Takes the scale factor as the second argument and an anchor point as the third argument.

The anchor point can take any of the following strings:

• center (default)
• topLeft
• topRight
• bottomRight
• bottomLeft

Returns a new shape array or an array of shape arrays, depending on input.

CommonJS

This is how you get to the good stuff if you're using require.

const Points = require( 'points' );
const add = Points.add;
const boundingBox = Points.boundingBox;
const cubify = Points.cubify;
const moveIndex = Points.moveIndex;
const offset = Points.offset;
const remove = Points.remove;
const reverse = Points.reverse;
const scale = Points.scale;

UMD

And if you just want to smash in a Javascript file you're also covered. Drop this in place ...

https://npmcdn.com/points@1.6.1/dist/points.min.js

Then access it on the Points global variable.

const add = Points.add;
const boundingBox = Points.boundingBox;
const cubify = Points.cubify;
const moveIndex = Points.moveIndex;
const offset = Points.offset;
const remove = Points.remove;
const reverse = Points.reverse;
const scale = Points.scale;

Help make this better

Issues and pull requests gratefully received!

I'm also on twitter @colinmeinke.

Thanks 🌟

License

ISC.