@thi.ng/geom-trace-bitmap

[!NOTE] This is one of 210 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

About

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 main traceBitmap() 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). See TraceBitmapOpts and example below for details.

Status

ALPHA - bleeding edge / work-in-progress

Search or submit any issues for this package

Related packages

• @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

Installation

yarn add @thi.ng/geom-trace-bitmap

ESM import:

import * as gtb from "@thi.ng/geom-trace-bitmap";

Browser ESM import:

<script type="module" src="https://esm.run/@thi.ng/geom-trace-bitmap"></script>

JSDelivr documentation

For Node.js REPL:

const gtb = await import("@thi.ng/geom-trace-bitmap");

Package sizes (brotli'd, pre-treeshake): ESM: 993 bytes

Dependencies

• @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)

Usage examples

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

API

Generated API docs

TODO

Basic usage

For brevity, this example uses thi.ng/pixel-io-netpbm to load an image in PGM format. For that image format, the read() function returns a thi.ng/pixel IntBuffer using the GRAY8 pixel format...

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" })
        )
    )
);

Authors

• Karsten Schmidt

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

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

License

© 2022 - 2025 Karsten Schmidt // Apache License 2.0