Artist SDK

01 / Modules

What’s included

The full SDK includes the modules below. Optional modules are imported separately, so importing the core does not start a renderer, panel, or viewer connection.

Paths beginning with …/ are subpaths of @oriel-art/artist-sdk.

02 / Integration example

Explore with Oriel

Try the SDK in Kepler’s Dream, a generative artwork by Mihira. Explore the parameter lab, play and seek through the animation, save and load recipes, and export a PNG.

Artwork by Mihira · Work in progress · Hosted on mihira.art
Built with Oriel Artist SDK 0.1.0-alpha.4, commit 33d529f. No local setup needed.

git clone https://github.com/oriel-art/artist-sdk.git
cd artist-sdk
npm run dev

03 / Integration

Add it to your artwork

Choose the setup that matches your project. These instructions use the repository source rather than assuming an npm registry release.

import { createArtwork } from './vendor/artist-sdk/src/index.js';

# From the artist-sdk checkout
npm ci
mkdir -p ../oriel-sdk-packages
npm pack --pack-destination ../oriel-sdk-packages
git rev-parse HEAD

# From your own project; adjust the path as needed
npm install ../oriel-sdk-packages/oriel-art-artist-sdk-0.1.0-alpha.4.tgz

A small first integration

After installing the package, save this as artwork.mjs and run node artwork.mjs. For the browser setup, replace the first line with the relative import above.

import { createArtwork } from '@oriel-art/artist-sdk';

const artwork = createArtwork({
  id: 'line-study',
  version: '1',
  seed: 'composition-001',
  parameters: {
    density: { type: 'integer', min: 8, max: 36, default: 16 },
    palette: { type: 'choice', choices: ['ink', 'clay'] }
  }
});

// Use these values in your own drawing code.
const density = artwork.parameters.density;
const random = artwork.random('composition');
const angle = random.float(0, Math.PI * 2);

// Save the inputs as JSON.
const recipe = JSON.stringify(artwork.getRecipe(), null, 2);
console.log({ density, angle, recipe });

This example produces values and a recipe; it does not draw an image. Pass those values into your own drawing code. Keep a random generator to advance its sequence—calling artwork.random('composition') again restarts that stream.

04 / Composition

Seeds, parameters & recipes

Seed

An exact string used to generate repeatable random choices. Separate named streams let you organize choices such as composition and colour.

Parameters

Numbers, integers, booleans, and choices with declared values and limits. Explicit values take priority over defaults; otherwise values can be sampled.

Recipe

A JSON record of artwork identity, versions, seed, and resolved parameters. Optional artist-defined context can record time, aspect ratio, or other state.

Your artwork supplies the restoration logic. A recipe is not a recording of simulation steps, GPU buffers, or interaction history. Keep matching artwork code and assets with it; restored inputs do not guarantee identical pixels on every device.

Explore parameters in the studio

The optional parameter panel provides sliders, precise entry, choice controls, boundary cases, and seed sampling reports. You supply the redraw callback and any checks for suitable compositions. The panel is available in studio mode; sampling alone does not establish artistic quality.

05 / Output

Rendering, export & print

Output size is checked against device limits and a pixel budget. The shader must support the requested size and aspect ratio; requests are not silently downscaled.

Describe what an output supports

Capabilities record technical limits and artist constraints such as image dimensions, formats, aspect ratios, physical print sizes, and DPI. Both sets of constraints apply. Validation returns supported, unsupported, or requires-evaluation.

Capture and screen one print job

The capture-and-screen workflow saves a composition, frame, output request, and print specification together. Artist-supplied checks run against that snapshot, so later live edits do not change the job.

Save the report with the exported image. Your integration handles rendering, colour profiles, and measurements; the SDK records the supplied checks and adds no print approval step.

06 / Artwork information

Metadata, discovery & viewers

Metadata describes the work: title, creators, editions, licensing, translations, and optional provenance references. These are artist-supplied descriptions; the SDK does not verify authorship or resolve references.

A declared capability does not implement a control or grant access to it. For example, advertising seek support and registering a seek command are separate decisions. Configure allowed viewer origins when exposing the bridge.

The optional information panel displays your own text, credits, and control descriptions inside the artwork. It works independently of the studio parameter editor.

07 / Status

Current limits

The SDK is experimental. The following are not provided by the current implementation:

• Automatic simulation replay or cross-device pixel identity.
• WebGL 2, textures, or multipass rendering in the optional shader runner.
• Video, frame-sequence or tiled export, colour management, or print profiles in that runner.
• Dedicated p5.js, Canvas 2D, Three.js, or platform publishing adapters.

You can still use the core utilities with your own renderer. Declarations and validation describe supported operations; they do not add an exporter or prove a rendering result.