@thi.ng/geom

@thi.ng/geom

npm versionnpm downloads Mastodon Follow

[!NOTE] This is one of 190 standalone projects, maintained as part of the @thi.ng/umbrella monorepo and anti-framework.

🚀 Please help me to work full-time on these projects by sponsoring me on GitHub. Thank you! ❤️

For the Clojure version, please visit: thi.ng/geom-clj

About

Functional, polymorphic API for 2D geometry types & SVG generation.

This project is a partially ported from the Clojure version of the same name. All polymorphic operations built on @thi.ng/defmulti.

Shape types

The following shape primitives are provided. For many there're multiple ways to create them, please check linked sources and/or docs.

Shape/FormDescriptionHiccup support
AABB3D Axis-aligned bounding box(2)
Arc2D elliptic arc
Circle2D circle
CubicnD cubic bezier(1)
Ellipse2D ellipse
Groupgroup of 2D shapes
Line2D line segment
Path2D path
Path (from SVG)2D path from SVG <path>
Plane3D plane(2)
Point cloudnD point cloud(1)
Polygon2D simple polygon (no holes)
Polyline2D polyline
Quad2D/3D quad (4-gon)(1)
QuadraticnD quadratic bezier(1)
RaynD ray(1)
Rectangle2D rectangle
Sphere3D sphere(2)
TextBasic stub for text labels(3)
Triangle2D triangle
  • (1) valid hiccup format, currently only useable/supported if 2D geometry
  • (2) valid hiccup format, currently unused/unsupported elsewhere
  • (3) merely treated as a point in space (e.g. used for placing text labels), no geometry of text itself

Hiccup support

With very few exceptions these all are implementing the IToHiccup interface and so can be easily converted (via hiccup) to a variety of other formats. By design, for better flexibility and performance reasons, the hiccup flavor used by this package is not compatible with that used by thi.ng/hiccup-svg, though the latter provides a convertTree() function for that purpose. This is only needed for some cases of dynamic in-browser SVG DOM creation...

SVG support

SVG conversion is included via the asSvg() and svgDoc() functions.

Polymorphic operations

The following operations are provided (many also applicable to shape groups directly and/or perform automatic resampling/conversion if needed).

OperationDescription
applyTransforms()applies any spatial transformation attributes
arcLength()compute arc length / perimeter of shape boundary
area()signed/unsigned surface area
asCubic()convert shape boundary to cubic bezier segments
asPath()convert shape to path
asPolygon()convert shape to polygon
asPolyline()convert shape to polyline
asSvg()serialize shape/group/hierarchy to SVG
bounds()compute bounding box
center()center shape around origin or point
centroid()compute shape centroid
classifyPoint()classify point in relation to shape boundary (in/out)
clipConvex()clip shape against convex boundary
closestPoint()compute closest point on shape boundary
convexHull()compute convex hull (2d only)
edges()extract edges
fitIntoBounds()rescale/reposition shapes into a destination boundary
flip()reverse order (vertices or direction)
intersects()pairwise shape intersection (various types)
mapPoint()transform world space point into local shape space
offset()shape/path offsetting
pointAt()compute point on shape boundary at parametric position
pointInside()check if point is inside shape
resample()resample/convert shape
rotate()rotate shape
scale()scale shape (uniformly/non-uniformly)
scatter()create random points inside a shape boundary
simplify()simplify shape/boundary (Douglas-Peucker)
splitArcLength()split shapes & groups based on max. arc length
splitAt()split shape/boundary at parametric position
splitNear()split shape/boundary near world position
subdivCurve()recursively apply curve subdivision kernel
tangentAt()compute tangent at parametric position
tessellate()(recursively) tessellate shape
transformVertices()apply custom function to each vertex
transform()apply transformation matrix
translate()translate shape
union()compute shape union
vertices()extract/sample vertices from shape boundary
volume()compute shape volume (3D only)
warpPoints()transfer points between the local spaces defined by 2 shapes
withAttribs()shallow copy of given shape with new attribs assigned

This package acts as a higher-level frontend for most of the following related packages (which are more low-level, lightweight and usable by themselves too):

Support packages

Related packages

Status

STABLE - used in production

Search or submit any issues for this package

Installation

yarn add @thi.ng/geom

ES module import:

<script type="module" src="https://cdn.skypack.dev/@thi.ng/geom"></script>

Skypack documentation

For Node.js REPL:

const geom = await import("@thi.ng/geom");

Package sizes (brotli'd, pre-treeshake): ESM: 13.25 KB

Dependencies

Usage examples

Several projects in this repo's /examples directory are using this package:

ScreenshotDescriptionLive demoSource
Basic 2D boid simulation and spatial indexing neighbor lookupsDemoSource
Self-modifying, animated typographic grid with emergent complex patternsDemoSource
Fiber-based cooperative multitasking basicsDemoSource
Convex hull & shape clipping of 2D polygonsDemoSource
geom-fuzz basic shape & fill examplesDemoSource
(Re)Constructing the thi.ng logo using a 2D signed-distance fieldDemoSource
2.5D hidden line visualization of digital elevation files (DEM)DemoSource
Animated, recursive polygon tessellationsDemoSource
Poisson-disk shape-aware sampling, Voronoi & Minimum Spanning Tree visualizationDemoSource
Mouse gesture / stroke analysis, simplification, corner detectionDemoSource
2D Bezier curve-guided particle systemDemoSource
Animated arcs & drawing using hiccup-canvasDemoSource
Canvas based Immediate Mode GUI componentsDemoSource
Animated sine plasma effect visualized using contour linesDemoSource
k-means clustering visualizationDemoSource
Live coding playground for 2D geometry generation using @thi.ng/pointfree-langDemoSource
2D Poisson-disc sampler with procedural gradient mapDemoSource
Polygon to cubic curve conversion & visualizationDemoSource
Animated, iterative polygon subdivisions & visualizationDemoSource
Quasi-random lattice generatorDemoSource
Minimal rdom-canvas animationDemoSource
Animated Voronoi diagram, cubic splines & SVG downloadDemoSource
2D scenegraph & shape pickingDemoSource
2D scenegraph & image map based geometry manipulationDemoSource
Compute cubic spline position & tangent using Dual NumbersDemoSource
SVG path parsing & dynamic resamplingDemoSource
3D wireframe textmode demoDemoSource
Multi-layer vectorization & dithering of bitmap imagesDemoSource

API

Generated API docs

TODO

Authors

If this project contributes to an academic publication, please cite it as:

@misc{thing-geom,
title = "@thi.ng/geom",
author = "Karsten Schmidt",
note = "https://thi.ng/geom",
year = 2013
}

License

© 2013 - 2024 Karsten Schmidt // Apache License 2.0

Generated using TypeDoc