rasterize

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
  • Circle
  • Line
  • Polygon / polyline
  • Rect
  • Flood fill
• Custom shaders
• Status
• Related packages
• Installation
• Dependencies
• Usage examples
• API
• Authors
• License

About

Headless 2D shape drawing, filling & rasterization for arbitrary targets/purposes (no canvas required).

The functions in this package can be used with any IGrid2D compatible grid/image type (e.g. those provided by @thi.ng/pixel or @thi.ng/text-canvas).

Currently the following functions are available. All of them support custom shader-like functions to produce "pixel" values.

Circle

• drawCircle(): Filled or outline implementation of Bresenham's circle algorithm, with clipping.

Line

• drawLine(): Implementation of Bresenham's line algorithm with pre-applied Liang-Barsky clipping
• traceLine(): Apply custom functions to trace the line

Polygon / polyline

Filled or outline drawing of polygons (without holes):

• drawPolyline()
• fillPoly()

Rect

• drawRect(): Filled or outline implementation with pre-applied clipping against the target grid.

Flood fill

• floodFill(): Fills grid in the connected region around x,y with given value or shader

Also see corresponding function in @thi.ng/grid-iterators.

Custom shaders

Conceptually similar, but not to be equaled with actual WebGL fragement shaders, many functions in this package support shader-like functions to produce per-pixel fill/color values for each individual pixel processed. These simple functions take an x and y arg (in grid-space, not normalized!) and produce a fill value for that location. A pixel is processed at most once per draw call.

The following shader functions are provided:

• defPattern(): pattern fill (must be same format as target grid)
• defStripes(): procedural stripes (configurable)
• defNoise(): random noise pattern (configurable)

As an example, here's a simple custom UV gradient shader for drawing into a float RGBA buffer:

import type { Shader2D } from "@thi.ng/rasterize";
import { floatBuffer } from "@thi.ng/pixel";
import { drawCircle } from "@thi.ng/rasterize";

// custom gradient shader
const defUVGradient = (width: number, height: number): Shader2D<number[]> =>
  (x, y) => [x/width, y/height, 0.5, 1];

const W = 256;

// create float RGBA pixel buffer
const img = floatBuffer(W, W);

// draw filled circle using gradient shader
drawCircle(img, W/2, W/2, W/2 - 4, defUVGradient(W, W), true);

Status

ALPHA - bleeding edge / work-in-progress

Search or submit any issues for this package

Related packages

• @thi.ng/grid-iterators - 2D grid and shape iterators w/ multiple orderings
• @thi.ng/pixel - Typedarray integer & float pixel buffers w/ customizable formats, blitting, drawing, convolution
• @thi.ng/text-canvas - Text based canvas, drawing, plotting, tables with arbitrary formatting (incl. ANSI/HTML)

Installation

yarn add @thi.ng/rasterize

ESM import:

import * as ras from "@thi.ng/rasterize";

Browser ESM import:

<script type="module" src="https://esm.run/@thi.ng/rasterize"></script>

JSDelivr documentation

For Node.js REPL:

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

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

Dependencies

• @thi.ng/api
• @thi.ng/checks
• @thi.ng/equiv
• @thi.ng/grid-iterators
• @thi.ng/porter-duff
• @thi.ng/random
• @thi.ng/transducers

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
	Steering behavior drawing with alpha-blended shapes	Demo	Source

API

Generated API docs

TODO

Authors

• Karsten Schmidt

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

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

License

© 2021 - 2024 Karsten Schmidt // Apache License 2.0