@thi.ng/rasterize

v1.0.172

Published

4 days ago

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

Downloads

1,079

0High
0Medium
0Low

thi.ng

2d bitmap circle clipping drawing floodfill grid iterator line pattern pixel polygon polyline rect shader shape typescript

npm downloads

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

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):

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

result image: circle with gradient fill

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

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
}