Procedural SVG drawings for a specified width and height, in PHP.

Generate landscapes, contours, partitions, flows, and density fields for a given canvas. Each drawing uses the requested width and height; some fill the viewport, while others leave transparent space between their shapes.

use Atelier\Field\Field;

echo Field::waves(360, 240, layers: 5, seed: 1)->withColor('#cf4d9b')->toSvg();

Examples from the catalogue: waves and low poly.

A field is an immutable drawing generated for one viewport. It produces standalone SVG, exports a CSS background, or supplies a group for an Atelier SVG document. For a surface that repeats, use the companion atelier/pattern package.

Colour · Catalogue · Errors · Gallery · Documentation

Installation

composer require atelier/field

Requires PHP 8.3+ and atelier/svg. Seeded generators use ext-random, bundled with PHP. Composer installs the package dependencies.

Quick start

Save a drawing as waves.svg:

<?php

declare(strict_types=1);

use Atelier\Field\Field;

require __DIR__.'/vendor/autoload.php';

$field = Field::waves(360, 240, layers: 5, seed: 1)->withColor('#cf4d9b');

file_put_contents(__DIR__.'/waves.svg', $field->toSvg());

Open waves.svg in a browser. The following snippets reuse $field, the imports, and the autoloader above. To append the drawing to an existing Atelier SVG document:

$document->getRootElement()?->appendChild($field->element());

Get CSS that uses the drawing as a background:

echo $field->toCss();

A background image is a document of its own, so currentColor resolves to black there. Set a real colour before calling toDataUri() or toCss().

Colour

Style methods return a new field, leaving the original unchanged:

echo $field->withColor('#0067a0')
    ->withBackground('#f6f5f1')
    ->withOpacity(0.6)
    ->toSvg();

The default foreground is currentColor and the background is transparent. Inline SVG inherits its colour from the surrounding page.

For a coordinated foreground, background, and palette, use a theme:

use Atelier\Field\Theme;

echo $field->withTheme(Theme::blueprint())->toSvg();

When a theme defines a palette, layers use those colours instead of the foreground colour. withColor() does not replace palette entries. Without a palette, layers use one colour at different opacities. See Colour.

Catalogue

Waves	Dunes	Strata
Mountains	Skyline	Cloud
Blob	Contours	Archipelago
Low poly	Voronoi	Foam
Flow field	Terrain	Halftone
Moire	Wave interference	Rays

Error handling

Width and height must be finite and greater than zero. Invalid dimensions or generator options throw Atelier\Field\Exception\InvalidArgumentException. All package exceptions implement Atelier\Field\Exception\ExceptionInterface.

See Input limits for validation examples and the viewport and precision limits before using extreme dimensions or sampling settings.

Gallery

From a repository checkout with dependencies installed:

composer gallery

Writes examples/output/index.html.

Documentation

• Getting started: install the package and produce a first SVG.
• Illustrated catalogue: choose a field and explore its parameters.
• Package overview: understand the API and its boundaries.

Read the complete guides and generated illustrations in docs/.

Contributing

Contributions are welcome. Visit the project on GitHub to report a bug, suggest a feature, or open a pull request.

Before submitting code, run:

composer qa
composer coverage

Changes to public behaviour need tests and a documentation update. Keep line coverage at 100%. Coverage reporting requires PCOV or Xdebug.

Support

Bug reports, security disclosures, and contribution guidelines are collected at ateliersvg.com/support.

License

Atelier Field is released under the MIT License.