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

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

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

ESM import:

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

Browser ESM import:

`html

`

JSDelivr documentation

For Node.js REPL:

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

Package sizes (brotli'd, pre-treeshake): ESM: 996 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

$3

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...

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

Authors

- Karsten Schmidt

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
}
``

License

© 2022 - 2026 Karsten Schmidt // Apache License 2.0