DOCSEARCHbyAlgolia
Submit Docs

flatten-js

repository·master·Indexed 20 days ago

https://github.com/alexbol99/flatten-js

A JavaScript library for manipulating abstract 2D geometric shapes including points, vectors, lines, circles, and polygons. It supports affine transformations, distance calculations, intersection finding, and boolean operations on polygons. The library includes a Planar Set for spatial queries and utilizes the DE-9IM model for describing spatial relationships. It provides an svg() method for shape visualization and supports CommonJS, UMD, and ES6 modules.

Tokens
17.1K
Snippets
72
Records
90
Agent score
70%

What's inside @flatten-js/core

  2. How Polygons work in flatten-js

    master

    A Polygon in flatten-js is a multi-polygon consisting of a collection of faces.

    Structure

    • Island: The most external face.
    • Hole: A face included within an island.
    • Nesting: Holes can contain inner islands, allowing for unlimited levels of inclusion.

    Requirements for Validity

    For boolean operations and relationship calculations to work correctly, polygons must be orientable:

    1. Faces must not have self-intersections.
    2. Faces must not overlap each other.
    3. Holes must have an orientation opposite to their surrounding islands.

    Use the isValid() method to check if a polygon meets these rules.

    Polygon Construction

    You can instantiate a Polygon using:

    • An array of shapes (Flatten.Segment or Flatten.Arc) representing closed chains.
    • An array of JSON objects representing closed chains.
    • An array of Flatten.Point instances.
    • An array of numeric pairs [x, y] representing vertices.
    • Instances of Circle or Box.

  3. Visualize shapes using the svg() method

    master
    While flatten-js is an abstract geometry library and does not handle rendering directly, all shape classes implement an svg() method. This method returns an SVG string that can be inserted into an SVG container in a web browser. It is designed to work well with libraries like d3js.

  4. Understand spatial relationships using the DE-9IM model

    master

    The library uses the Dimensionally Extended nine-Intersection Model (DE-9IM) to describe spatial relations between two geometries.

    The DE-9IM Matrix

    The model uses a 3x3 matrix representing the intersection of the Interior (I), Boundary (B), and Exterior (E) of two shapes (a and b).

    Accessing the Matrix

    You can access this matrix via Flatten.Relations.relate(shapeA, shapeB). The resulting object contains fields like I2I, B2I, E2I, I2B, etc.

    String Representation

    You can get a compact string representation of the matrix (where T is intersection, F is no intersection, and . is not applicable) using the toString() method on the matrix object.

    let {relate} = Flatten.Relations;
// define two shapes: polygon1, polygon2
let de9im = relate(polygon1, polygon2);

// explore fields of the de9im matrix:
de9im.I2I  de9im.B2I  de9im.E2I
de9im.I2B  de9im.B2B  de9im.E2B
de9im.I2E  de9im.B2E  // de9im.E2E is N/A

// Get string representation
let matrixString = de9im.toString();

  6. Use flatten-js in a browser as an ES6 module

    master

    You can use flatten-js directly in modern browsers that support <script type="module" without needing a build step or transpilation. The library can be imported as an ES module via unpkg.

    To run the example, simply open the index.html file in a browser. The library will generate SVG graphics based on the geometry logic defined in the script.

    <!-- Example of how to include the module in your HTML -->
<script type="module">
  import { Polygon } from 'https://unpkg.com/@flatten-js/core';
  // Your geometry logic here
</script>

  9. Use flatten-js in a browser via unpkg

    master

    To use flatten-js directly in a browser without a build step or transpilation, you can load the package via unpkg. The package is assigned to the window global scope under the name @flatten-js/core. You can then destructure the Flatten namespace from this global object to access the library's geometry functions and classes.

    // Accessing the library from the global scope
const { Flatten } = window['@flatten-js/core'];

  10. Import classes from @flatten-js/core

    master

    You can import geometry classes directly using named imports, or import the entire namespace as a default import and destructure it. The library supports CommonJS, UMD, and ES6 modules, and includes TypeScript definitions (index.d.ts) for static type checking.

    // Named imports
import {Point, Vector, Circle, Line, Ray, Segment, Arc, Box, Polygon, Matrix, PlanarSet} from '@flatten-js/core';

// Default import with destructuring
import Flatten from '@flatten-js/core';
const {Point, Vector, Circle, Line, Ray, Segment, Arc, Box, Polygon, Matrix, PlanarSet} = Flatten;

  12. Serialize and deserialize shapes using JSON

    master

    All shapes can be serialized to JSON strings using JSON.stringify() (which calls the internal .toJSON() method). To reconstruct a shape, parse the JSON and pass the resulting object to the shape's constructor.

    let {line, point} = Flatten;
let l = line(point(4, 0), point(0, 4));

// Serialize
let str = JSON.stringify(l);  

// Parse and reconstruct
let l_json = JSON.parse(str);
let l_parsed = line(l_json);