Autopen

A compact signature serialization library for capturing, encoding, and rendering hand-drawn signatures.

Live Demo

Features

• Compact encoding: Typical signatures serialize to 100-200 bytes
• Multiple text encodings: Z85 (compact), Base64, Base64URL (URL-safe)
• Vectorization: Raw input points are simplified to efficient vector strokes
• SVG rendering: Generate clean SVG output with spline interpolation and content fitting
• No dependencies: Pure TypeScript, works in browsers and Node.js
• Forward-compatible: Versioned binary format with CRC-8 error detection

Installation

npm install autopen

Or use directly from a CDN:

<script type="module">
  import { Signature, Encoding, Format } from "https://esm.sh/autopen";
</script>

Quick Start

import { Signature, Encoding, Format } from "autopen";

// Create a signature and add strokes
const sig = new Signature({
  canvasWidth: 400, // Your canvas dimensions
  canvasHeight: 200,
});

// Add strokes (arrays of {x, y} points from your drawing canvas)
sig.pushStroke([
  { x: 50, y: 100 },
  { x: 100, y: 80 },
  { x: 150, y: 120 },
  // ... more points
]);

// Serialize to different formats
const bytes = sig.serialize(); // Uint8Array
const z85 = sig.serializeToString(Encoding.Z85); // Compact text
const b64url = sig.serializeToString(Encoding.BASE64URL); // URL-safe

// Deserialize
const fromBytes = Signature.deserialize(bytes);
const fromZ85 = Signature.deserializeFromString(z85, Encoding.Z85);

// Render to SVG
const svg = fromZ85.render(Format.SVG, {
  width: 512,
  height: 256,
  strokeColor: "#000000",
  strokeWidth: 2,
});

API Reference

new Signature(options)

Create a new signature object.

| Option | Type | Default | Description | | ----------------- | ------ | ------- | ------------------------------------------------------------------------------------------- | | simplifyEpsilon | number | 2 | Tolerance for Ramer-Douglas-Peucker simplification. Higher = fewer points = smaller output. | | canvasWidth | number | 512 | Your input canvas width for coordinate scaling. | | canvasHeight | number | 256 | Your input canvas height for coordinate scaling. |

Instance Methods

pushStroke(points)

Add a stroke to the signature. Points should be {x, y} objects in your canvas coordinate space.

sig.pushStroke([
  { x: 10, y: 20 },
  { x: 15, y: 25 },
  { x: 20, y: 22 },
]);

The stroke is automatically simplified using the Ramer-Douglas-Peucker algorithm to reduce point count while preserving shape.

popStroke()

Remove and return the last stroke (in your canvas coordinates). Returns null if empty. Useful for implementing undo.

const removed = sig.popStroke();

getStrokes()

Get all strokes (simplified, in your canvas coordinates).

const strokes = sig.getStrokes();
for (const stroke of strokes) {
  console.log("Stroke:", stroke.length, "points");
}

clear()

Remove all strokes.

isEmpty()

Returns true if the signature has no strokes.

strokeCount

Property returning the number of strokes.

clone()

Create a deep copy of the signature.

serialize()

Serialize the signature to binary.

const bytes = sig.serialize(); // Returns Uint8Array

serializeToString(encoding)

Serialize the signature to an encoded string.

const z85 = sig.serializeToString(Encoding.Z85); // Compact
const b64 = sig.serializeToString(Encoding.BASE64); // Standard base64
const b64url = sig.serializeToString(Encoding.BASE64URL); // URL-safe

render(format, options)

Render the signature to the specified format.

const svg = sig.render(Format.SVG, {
  width: 512, // Output width (default: 512)
  height: 256, // Output height (default: 256)
  strokeWidth: 2, // Line width in pixels (default: 2)
  strokeColor: "#000", // Stroke color (default: '#000000')
  spline: true, // Use Catmull-Rom spline interpolation (default: true)
  splineTension: 0.5, // Spline tension 0-1 (default: 0.5)
  backgroundColor: null, // Background color, null for transparent (default: null)
  contentFit: true, // Fit to content bounds instead of full canvas (default: true)
  contentPadding: 0.05, // Padding as fraction of output dims when contentFit=true (default: 0.05)
});

Content Fitting: When contentFit is true, the SVG scales to fit the actual signature bounds (plus padding) rather than the full internal canvas. This eliminates whitespace around signatures that don't fill the canvas. Set contentFit: false to always use the full internal canvas bounds.

getInternals()

Access version-specific internals for analysis/debugging.

const internals = sig.getInternals();

// Get normalized strokes (in 512x256 internal space)
const normalized = internals.getNormalizedStrokes();

// Get raw delta-encoded payload bytes (before compression)
const payload = internals.getPayloadBytes();

// Get encoding statistics
const stats = internals.getEncodeStats();
// { deltas, absolutes, strokeMarkers, overflowDxOnly, overflowDyOnly, overflowBoth }

// Get delta frequency distributions
const { dx, dy, joint } = internals.getDeltaFrequencies();

// Get byte frequency distribution
const byteFreq = internals.getByteFrequencies();

// Get the arithmetic coder (for analysis)
const coder = internals.getArithmeticCoder();

Static Methods

Signature.deserialize(data, options)

Deserialize a signature from binary data.

const sig = Signature.deserialize(uint8Array, {
  canvasWidth: 400,
  canvasHeight: 200,
});

Signature.deserializeFromString(data, encoding, options)

Deserialize a signature from an encoded string.

const sig = Signature.deserializeFromString(z85String, Encoding.Z85, {
  canvasWidth: 400,
  canvasHeight: 200,
});

Signature.fromNormalizedStrokes(strokes, options)

Advanced: Create a Signature from strokes already in the internal 512x256 coordinate space. Bypasses simplification and coordinate scaling.

const sig = Signature.fromNormalizedStrokes(normalizedStrokes, {
  canvasWidth: 400,
  canvasHeight: 200,
});

Enums

Encoding

Encoding.Z85; // Z85 encoding (25% overhead, not URL-safe)
Encoding.BASE64; // Standard base64 (33% overhead)
Encoding.BASE64URL; // URL-safe base64 (33% overhead)

Format

Format.SVG; // SVG string output

Exports

Stable API (safe for production use)

| Export | Description | | ----------- | ------------------------------------------------------ | | Signature | Main signature class | | Encoding | Encoding enum (BINARY, Z85, BASE64, BASE64URL) | | Format | Output format enum (SVG) |

TypeScript Types

| Export | Description | | ------------------ | ------------------------------------------- | | Point | Interface for 2D point ({x, y}) | | Stroke | Type alias for Point[] | | SignatureOptions | Options for new Signature() | | RenderOptions | Options for render() | | EncodeStats | Encoding statistics from getEncodeStats() | | DeltaFrequencies | Delta frequency data for analysis | | EncodingType | Union type for Encoding values | | FormatType | Union type for Format values |

Advanced/Analysis (may change in minor versions)

| Export | Description | | ------------------------ | ---------------------------------------------- | | SignatureV1Internals | V1 internals class for analysis (unstable) | | V1_CANVAS_WIDTH | V1 internal width (512) | | V1_CANVAS_HEIGHT | V1 internal height (256) | | DEFAULT_EPSILON | Default simplification tolerance (2) | | DEFAULT_SPLINE_TENSION | Default spline tension (0.5) | | MAX_TOTAL_POINTS | Maximum points allowed (100,000) | | VERSION | Current format version (1) | | MAGIC | Magic byte (0x53 = 'S') |

Utilities (may change in minor versions)

| Export | Description | | ------------------------------- | -------------------------------------------------- | | simplifyPolyline | Ramer-Douglas-Peucker simplification | | computeCRC8 | CRC-8-CCITT checksum | | z85Encode / z85Decode | Z85 encoding (note: decode expects Autopen format) | | base64Encode / base64Decode | Base64 encoding |

Format Specification

Stability Guarantees

The binary format is designed for long-term storage:

• Envelope structure is frozen: Magic byte, version byte, length field, and CRC-8 positions will never change
• V1 payloads will always be decodable: Future library versions will continue to decode V1 data
• CRC-8 ensures integrity: Corrupted data is detected and rejected

Envelope (version-independent)

+-------+---------+-----+---------+-----+
| MAGIC | VERSION | LEN | PAYLOAD | CRC |
| 1B    | 1B      | 2B  | var     | 1B  |
+-------+---------+-----+---------+-----+

| Field | Size | Description | | ------- | -------- | ----------------------------------------------------------------- | | MAGIC | 1 byte | 0x53 ('S') - Identifies Autopen format | | VERSION | 1 byte | Payload format version | | LEN | 2 bytes | Big-endian uint16, length of PAYLOAD (max 65535) | | PAYLOAD | variable | Version-specific opaque bytes | | CRC | 1 byte | CRC-8-CCITT (polynomial 0x07) over bytes 0 through end of PAYLOAD |

V1 Payload Structure

+----------+------------+
| ORIG_LEN | COMPRESSED |
| 2B       | var        |
+----------+------------+

| Field | Size | Description | | ---------- | -------- | ---------------------------------------------------- | | ORIG_LEN | 2 bytes | Big-endian uint16, length of uncompressed delta data | | COMPRESSED | variable | Arithmetic-coded delta data |

V1 Delta Encoding

Coordinates are stored in a 512x256 internal space (9-bit X, 8-bit Y).

2-byte delta (most common, covers ~98% of points):

• Byte 0: dx + 125 (range 0x00-0xFB, dx in [-125, +126])
• Byte 1: dy + 127 (range 0x00-0xFF, dy in [-127, +128])

3-byte commands (control bytes 0xFC-0xFF):

| Byte | Command | Description | | ---- | --------- | --------------------------- | | 0xFC | STROKE_LO | New stroke, X < 256 | | 0xFD | STROKE_HI | New stroke, X >= 256 | | 0xFE | ABS_LO | Absolute position, X < 256 | | 0xFF | ABS_HI | Absolute position, X >= 256 |

For 3-byte commands: byte 1 = X & 0xFF, byte 2 = Y.

V1 Arithmetic Coding

Delta data is compressed using arithmetic coding with a static Laplacian probability model optimized for signature data. Typical compression: 20-40%.

Text Encodings

| Encoding | Overhead | URL-Safe | Use Case | | --------- | -------- | -------- | ---------------------- | | Z85 | 25% | No | Database storage, APIs | | Base64 | 33% | No | General interchange | | Base64URL | 33% | Yes | URLs, query parameters |

Coordinate Scaling

Signatures are internally stored in a 512x256 coordinate space. The canvasWidth and canvasHeight options control automatic scaling using "contain" fit (uniform scale, preserving aspect ratio, centered).

// Your 400x200 canvas maps to the internal 512x256 space
const sig = new Signature({ canvasWidth: 400, canvasHeight: 200 });

// pushStroke() converts your coordinates to internal space
sig.pushStroke([{ x: 200, y: 100 }]); // Center of your canvas

// getStrokes() converts back to your coordinates
const strokes = sig.getStrokes(); // Points in 400x200 space

// When deserializing, specify your canvas dimensions to get correct scaling
const restored = Signature.deserializeFromString(z85, Encoding.Z85, {
  canvasWidth: 400,
  canvasHeight: 200,
});

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test           # Watch mode
npm run test:run   # Single run

# Development mode (watch)
npm run dev

Demo

The demo page is available at schlarpc.github.io/autopen.

To run locally:

npm run demo          # Start dev server with hot reload
npm run demo:build    # Build for production
npm run demo:preview  # Preview production build

Error Handling

The library throws descriptive errors for various failure conditions:

Deserialization Errors

try {
  const sig = Signature.deserialize(data);
} catch (e) {
  // Possible errors:
  // - "Data must be Uint8Array; use deserializeFromString for encoded strings"
  // - "Data too short: X bytes (minimum 5)"
  // - "Invalid magic byte: 0xXX (expected 0x53)"
  // - "Unsupported version: X"
  // - "Truncated data: expected X bytes, got Y"
  // - "CRC mismatch: expected 0xXX, got 0xYY"
}

String Decoding Errors

try {
  const sig = Signature.deserializeFromString(encoded, Encoding.Z85);
} catch (e) {
  // Possible errors:
  // - "Invalid Z85 string: length X is not a multiple of 5"
  // - "Invalid Z85 string: unexpected character 'X' at position Y"
  // - "Invalid base64 string: length X after padding removal is 1 mod 4"
  // - "Invalid base64 string: unexpected character 'X' at position Y"
}

Input Validation Errors

try {
  const sig = new Signature({ canvasWidth: 0 });
} catch (e) {
  // "Canvas dimensions must be positive (got 0×256)"
}

try {
  // Adding too many points (> 100,000 total)
  sig.pushStroke(hugeArrayOfPoints);
} catch (e) {
  // "Cannot add stroke: would exceed maximum of 100000 total points"
}

Note: Invalid coordinates (NaN, Infinity) are silently filtered out rather than throwing errors, allowing partial recovery from corrupted input data.

Runtime Requirements

Node.js: Requires Node.js 18 or later (ES2022 features).

Browsers: Requires ES module support. Compatible with all evergreen browsers:

• Chrome/Edge 61+
• Firefox 60+
• Safari 11+
• Mobile Safari/Chrome (iOS 11+, Android Chrome 61+)

No transpilation or polyfills needed.

License

MIT