DOCSEARCHbyAlgolia
Submit Docs

canvas-sketch

repository·master·Indexed 26 days ago

https://github.com/mattdesl/canvas-sketch

A toolkit for generative artists to create, develop, and export high-quality digital and physical artwork using JavaScript and the HTML5 Canvas API. It supports exporting high-resolution PNGs, image sequences for GIF/MP4, and SVG files for pen plotters. The library integrates with graphics libraries such as ThreeJS, P5.js, Pixi, Regl, and D3, and includes a CLI for scaffolding, hot reloading, and building sketches.

Tokens
13.2K
Snippets
44
Records
80
Agent score
89%

What's inside canvas-sketch

  1. Overview of canvas-sketch

    master

    canvas-sketch is a collection of tools and modules for creating generative art in JavaScript and the browser using the <canvas> tag. It is designed for creating artworks using code, randomness, and algorithms.

    Key capabilities include:

    • Exporting high-resolution PNGs for Giclée prints.
    • Rendering image sequences for GIF and MP4 loops.
    • Generating SVG files for mechanical pen plotters (e.g., AxiDraw).
    • Automatic git hashing for long-term archiving.
    • Integration with graphics libraries like ThreeJS, P5.js, Pixi, Regl, and D3.

  2. Enable Hot Reloading with the --hot flag

    master

    You can use Hot Reloading to apply code changes without a full page reload. This preserves the { time } and { frame } parameters of animated sketches and provides a smoother development feedback loop.

    Requirements: You must be using canvas-sketch@0.0.25 and canvas-sketch-cli@1.0.21 or newer.

    canvas-sketch my-sketch.js --hot

  3. Run and develop sketches

    master

    To run an existing sketch, simply pass the filename to the CLI. This starts a development server.

    Development Features:

    • Hot Reloading: Use the --hot flag to enable hot reloading during development.
    • Asset Paths: If building into a subdirectory like public/, use --dir to ensure assets load with correct paths.
    • Browserify Arguments: You can pass arguments to Browserify by using a -- separator after the CLI options.

    Examples:

    Run an existing sketch:

    canvas-sketch mysketch.js

    Run with Hot Reloading:

    canvas-sketch mysketch.js --hot

    Run with a specific directory for assets:

    canvas-sketch mysketch.js --dir public

    Pass a Browserify transform:

    canvas-sketch mysketch.js -- -t bubleify
    canvas-sketch mysketch.js --hot

  4. Install the canvas-sketch-cli globally

    master

    To install the CLI tool globally so you can use the canvas-sketch command directly in any terminal session, use the --global flag.

    If you encounter errors during global installation, refer to the troubleshooting guide regarding EACCES errors.

    npm install canvas-sketch-cli --global

  5. Enable animation in canvas-sketch

    master

    To create animated artworks, include animate: true in your settings object. This initiates a requestAnimationFrame loop once the sketch is loaded.

    When animating, you can use the following properties provided in the renderer function's props object:

    • time: The current time of the loop in seconds. Use this for endless loops with no fixed duration.
    • playhead: A value in the 0..1 range. This is only defined when a fixed duration is specified in settings. Use this for seamless loops (e.g., by multiplying by Math.PI).
    • frame: The current frame index of the animation.

    To ensure a seamless loop, multiply the playhead by Math.PI to create a value that wraps around perfectly.

    const canvasSketch = require('canvas-sketch');

const settings = {
  animate: true,
  duration: 3,
  dimensions: [ 256, 256 ],
  fps: 30
};

canvasSketch(() => {
  return ({ context, width, height, playhead }) => {
    // Use playhead for seamless rotation
    const rotation = playhead * Math.PI;
    
    // ... drawing logic
  };
}, settings);

  6. Stream animations to MP4 or GIF using FFMPEG

    master

    If ffmpeg is installed on your system, you can stream animation frames directly into an MP4 or GIF file instead of exporting individual images. This requires canvas-sketch@0.5.x and canvas-sketch-cli@1.6.x or higher.

    Streaming Options (Sub-arguments): Pass these after the --stream flag:

    • --scale, -s: Scale width:height (use -1 for auto/preserve aspect ratio).
    • --time, -t: Duration (e.g., -t=4s).
    • --start, -s: Start time (e.g., -s=1s).

    Examples:

    Stream to MP4 (default):

    canvas-sketch animation.js --output=tmp --stream

    Stream to GIF:

    canvas-sketch animation.js --output=tmp --stream=gif

    Stream to GIF with scaling:

    canvas-sketch animation.js --output=tmp --stream [ gif --scale=512:-1 ]
    canvas-sketch animation.js --output=tmp --stream

  7. Scaffold a Live Shader coding environment

    master

    You can create a dedicated live-coding environment for GLSL shaders using the shader template. This template uses canvas-sketch-util/shader and enables hot-reloading so that shader changes are reflected immediately upon saving.

    canvas-sketch test.js --new --template=shader --hot --open

  8. Build a sketch into a static website

    master

    Use the --build flag to generate static HTML and JS files suitable for web hosting.

    Build Options:

    • --no-compress: Disable compression/minification during the build.
    • --inline: Inline all JS into a single HTML file.
    • --name: The name of the JS file (defaults to input filename).
    • --html: The HTML input file (defaults to a basic template).
    • --js: The served JS src string.

    Custom HTML Templates: If you provide a custom HTML file via --html, you can include the {{entry}} placeholder. The build tool will replace this with the appropriate <script> tag.

    Examples:

    Build to a public/ folder without minification:

    canvas-sketch mysketch.js --dir public --build --no-compress

    Build into a single standalone index.html file:

    canvas-sketch mysketch.js --name index --build --inline

    Build using a custom HTML and JS file:

    canvas-sketch src/index.js --html=src/page.html --js=bundle.js
    canvas-sketch mysketch.js --dir public --build --no-compress

  10. Create a new sketch with templates

    master

    You can scaffold a new sketch file using the --new flag. You can specify a template to pre-configure the environment.

    Supported Templates:

    • default
    • p5
    • penplot
    • regl
    • shader
    • three
    • two

    You can also provide a path to a custom template file.

    Examples:

    Create a new ThreeJS sketch and open it in the browser:

    canvas-sketch sketch.js --new --template=three --open

    Use a custom template file:

    canvas-sketch sketch.js --template=./mytemplate.js

    Create a sketch by piping code from the clipboard (macOS):

    pbpaste | canvas-sketch --new --open
    canvas-sketch sketch.js --new --template=three --open

  12. Quick Start with canvas-sketch-cli

    master

    To quickly scaffold a new generative sketch, use npx canvas-sketch-cli. This command allows you to create a new sketch.js file and immediately open it in your browser.

    Requirements: node@15.x and npm@7.x or newer.

    mkdir my-sketches
cd my-sketches
npx canvas-sketch-cli sketch.js --new --open