Bitmap image to hairline vector and point cloud conversions
npm install @thi.ng/geom-trace-bitmap
!npm downloads

> [!NOTE]
> This is one of 214 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! ❤️
- About
- Status
- Related packages
- Installation
- Dependencies
- Usage examples
- API
- Basic usage
- Authors
- License
Bitmap image to hairline vector and point cloud conversions. This is a support package for @thi.ng/geom.
This package provides an extensible setup to extract user selectable
single-pixel width line segments in horizontal, vertical and diagonal (45°)
directions and/or single pixels as 2d point cloud. The maintraceBitmap()
function supports a predicate function to filter qualifying pixel values,
options to control which line orientations should be considered (incl. providing
custom ones and in which order of application), as well as a 2x3 matrix to
transform extracted points (pixel coordinates). SeeTraceBitmapOpts
and example below for details.
ALPHA - bleeding edge / work-in-progress
Search or submit any issues for this package
- @thi.ng/geom-axidraw - Conversion and preparation of thi.ng/geom shapes & shape groups to/from AxiDraw pen plotter draw commands
- @thi.ng/pixel - Typedarray integer & float pixel buffers w/ customizable formats, blitting, drawing, convolution
``bash`
yarn add @thi.ng/geom-trace-bitmap
ESM import:
`ts`
import * as gtb from "@thi.ng/geom-trace-bitmap";
Browser ESM import:
`html`
For Node.js REPL:
`js`
const gtb = await import("@thi.ng/geom-trace-bitmap");
Package sizes (brotli'd, pre-treeshake): ESM: 996 bytes
- @thi.ng/api
- @thi.ng/errors
- @thi.ng/grid-iterators
- @thi.ng/matrices
- @thi.ng/pixel
- @thi.ng/vectors
Note: @thi.ng/api is in _most_ cases a type-only import (not used at runtime)
One project in this repo's
/examples
directory is using this package:
| Screenshot | Description | Live demo | Source |
|:--------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------|:---------------------------------------------------|:--------------------------------------------------------------------------------|
|
| Multi-layer vectorization & dithering of bitmap images | Demo | Source |
TODO
For brevity, this example uses
thi.ng/pixel-io-netpbm
to load an image in PGM format. For that image format, the read() functionGRAY8
returns a thi.ng/pixel
IntBuffer using the
pixel format...
`ts tangle:export/readme.ts
import { asSvg, group, line, points, svgDoc } from "@thi.ng/geom";
import { traceBitmap } from "@thi.ng/geom-trace-bitmap";
import { read } from "@thi.ng/pixel-io-netpbm";
import { readFileSync, writeFileSync } "node:fs";
// vectorize bitmap, the returned arrays contain:
// - pairs of vectors (line segments)
// - vectors (points)
const { lines, points: dots } = traceBitmap({
// source image (WILL be mutated!)
img: read(readFileSync("foo.pgm")),
// pixel selection predicate (here to select all bright pixels)
select: (x) => x > 128,
// process horizontals, verticals, diagonals & points (default)
// see: https://docs.thi.ng/umbrella/geom-trace-bitmap/types/TraceDir.html
dir: ["h", "v", "d1", "d2", "p"]
});
// write extracted geometry as SVG file
writeFileSync(
"export/trace.svg",
asSvg(
svgDoc(
{},
group({}, lines.map(([a,b]) => line(a, b))),
points(dots, { fill: "#000", stroke: "none" })
)
)
);
`
If this project contributes to an academic publication, please cite it as:
`bibtex``
@misc{thing-geom-trace-bitmap,
title = "@thi.ng/geom-trace-bitmap",
author = "Karsten Schmidt",
note = "https://thi.ng/geom-trace-bitmap",
year = 2022
}
© 2022 - 2026 Karsten Schmidt // Apache License 2.0