Skip to content

Latest commit

 

History

History
168 lines (127 loc) · 6.63 KB

README.md

File metadata and controls

168 lines (127 loc) · 6.63 KB
Raw

@thi.ng/geom-trace-bitmap

npm version npm downloads Mastodon Follow

Note

This is one of 199 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

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

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

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 - 2024 Karsten Schmidt // Apache License 2.0