p5.plotsvg/documentation.md

A Plotter-Oriented SVG Exporter for p5.js

<!-- 
// previously generated documentation using: 
// npx documentation build p5.plotSvg.js -f md -o docs --shallow
// ...but now edited by hand, sorry
-->

# p5.plotSvg Documentation

p5.plotSvg can be used through global functions, through the `p5plotSvg`
namespace, or through p5 add-on-style methods attached to p5 sketch instances.
Existing global usage remains supported for backward compatibility with older
sketches and p5.js v1 projects.

### Table of Contents

*   [beginRecordSvg](#beginrecordsvg)
*   [pauseRecordSvg](#pauserecordsvg)
*   [endRecordSvg](#endrecordsvg)
*   [setSvgDocumentSize](#setsvgdocumentsize)
*   [setSvgResolutionDPI](#setsvgresolutiondpi)
*   [setSvgResolutionDPCM](#setsvgresolutiondpcm)
*   [setSvgInkscapeCompatibility](#setsvginkscapecompatibility)
*   [setSvgDefaultStrokeWeight](#setsvgdefaultstrokeweight)
*   [setSvgDefaultStrokeColor](#setsvgdefaultstrokecolor)
*   [setSvgBackgroundColor](#setsvgbackgroundcolor)
*   [setSvgIndent](#setsvgindent)
*   [setSvgFlattenTransforms](#setsvgflattentransforms)
*   [setSvgCoordinatePrecision](#setsvgcoordinateprecision)
*   [setSvgTransformPrecision](#setsvgtransformprecision)
*   [setSvgPointRadius](#setsvgpointradius)
*   [setSvgGroupByStrokeColor](#setsvggroupbystrokecolor)
*   [setSvgMergeNamedGroups](#setsvgmergenamedgroups)
*   [setSvgExportPolylinesAsPaths](#setsvgexportpolylinesaspaths)
*   [setSvgExportMalformedNumbersWithSanitizations](#setsvgexportmalformednumberswithsanitizations)
*   [setSvgClampLargeCoordinates](#setsvgclamplargecoordinates)
*   [setSvgCoordinateClampMagnitude](#setsvgcoordinateclampmagnitude)
*   [beginSvgGroup](#beginsvggroup)
*   [endSvgGroup](#endsvggroup)
*   [getDefaultStrokeColor](#getdefaultstrokecolor)
*   [isRecordingSVG](#isRecordingSVG)
*   [Experimental Extension Hooks](#experimental-extension-hooks)


<!-- WORK IN PROGRESS
*   [injectSvgHeaderAttribute](#injectsvgheaderattribute)
*   [injectSvgDef](#injectsvgdef) 
-->


---


## beginRecordSvg

Begins recording SVG output for a p5.js sketch.
Initializes recording state, validates and sets the output filename,
and overrides p5.js drawing functions to capture drawing commands for SVG export.

Supported forms:

```js
beginRecordSvg(this, "file.svg");        // legacy explicit p5 instance form
beginRecordSvg("file.svg");              // global-mode add-on style
sketch.beginRecordSvg("file.svg");       // instance-mode add-on style
p5plotSvg.beginRecordSvg(this, null);    // namespace form, no file download
```

#### Parameters
*   `p5Instance` **[object][26] | [string][27] | null** A reference to the current p5.js sketch (e.g. `this`) when using the legacy explicit form, or a filename/null when using add-on-style global or instance methods.
*   `fn` **[string][27]? | null** Optional filename for the output SVG file when using the explicit p5 instance form. The explicit use of `null` will prevent a file from being saved.


## pauseRecordSvg

Pauses or unpauses recording of SVG output for a p5.js sketch,
depending on whether the boolean `bPause` argument is `true` or `false`.

#### Parameters
*   `bPause ` **[boolean][29]**


## endRecordSvg

Ends recording of SVG output for a p5.js sketch. Calls the export function to generate the SVG output and restores the original p5.js functions. Returns the complete text of the SVG file as a string.

When used as an add-on-style instance method, call it as `sketch.endRecordSvg()`.
The global form `endRecordSvg()` and namespace form `p5plotSvg.endRecordSvg()`
remain supported.


## setSvgDocumentSize

Sets the dimensions of the SVG document in pixels/dots. 
Note that graphics are not scaled to fit this size; they may extend beyond the specified dimensions. 
If this is not set, the system will default to the main canvas dimensions (i.e. from `createCanvas()`).

#### Parameters
*   `w` **[number][28]** The SVG document width in pixels/dots. Must be a positive number.
*   `h` **[number][28]** The SVG document height in pixels/dots. Must be a positive number.


## setSvgResolutionDPI

Sets the resolution for the exported SVG file in dots per inch (DPI).
This value is used to determine the scaling of units (pixels to physical dimensions) in the SVG output. The default is 96 dpi. 

#### Parameters
*   `dpi` **[number][28]** The resolution in dots per inch. Must be a positive number.


## setSvgResolutionDPCM

Sets the resolution for the exported SVG file in dots per centimeter (DPCM).
This value is used to determine the scaling of units (pixels to physical dimensions) in the SVG output. The default resolution is approximately `37.79527559` dpcm (equivalent to 96 dpi). 

#### Parameters
*   `dpcm` **[number][28]** The resolution in dots per centimeter. Must be a positive number.


## setSvgInkscapeCompatibility

Enables or disables Inkscape-compatible layer attributes for SVG groups.
When enabled (which is the default), Inkscape headers will be added to the SVG, and SVG groups created with `beginSvgGroup()` will include
`inkscape:groupmode="layer"` and auto-numbered `inkscape:label` attributes. Disabling this mode produces 'vanilla' SVG files.

#### Parameters

*   `bEnabled` **[boolean][29]** Enable or disable Inkscape layer compatibility. The default is `true`: groups will include Inkscape layer attributes, and the SVG file will have Inkscape hints in its headers.


## setSvgDefaultStrokeWeight

Sets the default stroke weight for SVG elements.

#### Parameters
*   `wei` **[number][28]** The stroke weight to set.


## setSvgDefaultStrokeColor

Sets the default stroke color for SVG elements.

#### Parameters
*   `col` **[string][27]** The stroke color to set, in valid CSS color format.


## setSvgBackgroundColor

Sets an optional background color (as a CSS style) for the SVG. This is independent of the `background()` color of the p5 sketch. 
This color does not interfere with plotter output and is purely for visualization. Note that this color may not be visible in all SVG viewers. If this function is not called, no background color style is specified in the SVG.

#### Parameters
*   `col` **[string][27]** The background color to set, in valid CSS color format.


## setSvgIndent

Sets the type and amount of indentation used for formatting SVG output.
The function allows for spaces, tabs, or no indentation.

#### Parameters
*   `itype` **[string][27]** The type of indentation to use. Valid values are
    'SVG\_INDENT\_SPACES', 'SVG\_INDENT\_TABS', or 'SVG\_INDENT\_NONE'.
*   `inum` **[number][28]?** Optional number of spaces or tabs to use for indentation.
    Must be a non-negative integer if provided. Defaults to 2 for spaces and 1 for tabs.


## setSvgFlattenTransforms

Set whether or not to use a stack to encode matrix transforms.

* `setSvgFlattenTransforms(true)` -- larger SVG files, greater fidelity to original
* `setSvgFlattenTransforms(false)` -- smaller SVG files, potentially less fidelity

#### Parameters
*   `b` **[boolean][29]** Whether or not to flatten geometric transforms


## setSvgCoordinatePrecision

Sets the output precision for graphics coordinates in SVGs by adjusting
the number of decimal digits used when formatting values. Default is 4 digits. 

#### Parameters
*   `p` **[number][28]** The desired number of decimal digits for coordinates.
    Must be a non-negative integer. If an invalid value is provided, a warning is issued.


## setSvgTransformPrecision

Sets the output precision for matrix-transform values in SVGs by adjusting
the number of decimal digits used when formatting rotations, translations, etc. Default is 6 digits. 

#### Parameters
*   `p` **[number][28]** The desired number of decimal digits for matrix values.
    Must be a non-negative integer. If an invalid value is provided, a warning is issued.


## setSvgPointRadius

Sets the radius for "points" (which are rendered as tiny circles) in the SVG output. Default is 0.25 pixels.

#### Parameters
*   `radius` **[number][28]** The desired radius for points, specified as a positive number.
    If an invalid value (non-positive or non-number) is provided, a warning is issued.


## setSvgGroupByStrokeColor

Sets whether or not to group SVG elements by stroke color. When true, elements with the same stroke color, at the same level, will be grouped together.

#### Parameters

*   `bEnabled` **[boolean][29]** Enable or disables grouping of elements by stroke color. The default is `false`.


## setSvgMergeNamedGroups

Sets whether or not to merge user-defined SVG groups that have the same name. 
Useful for grouping paths that might be computed at different times, but which are part of the same compositional design element, and should be plotted with the same drawing tool. The default is `true`, meaning that groups with the same name (which are at the same hierarchical level) will be merged. *Note*: There may be unexpected groupings if `setSvgGroupByStrokeColor()` is also set to `true`. 

#### Parameters
*   `bEnabled` **[boolean][29]** Whether or not groups with the same name should be merged.


## setSvgExportPolylinesAsPaths

Sets whether all polylines should be exported as `<path>` elements instead of the default case (which is `<polyline>` or `<polygon>`). This can be useful for extension code or downstream tools that require path elements.

#### Parameters
*   `b` **[boolean][29]** `true` to export polylines as `<path>` elements; `false` to keep the default behavior.


## setSvgExportMalformedNumbersWithSanitizations

Sets whether malformed numeric values are sanitized or omitted from SVG output.
The default is `true`, meaning that non-finite values such as `NaN`, `Infinity`,
and `-Infinity` are clobbered to `0` during SVG serialization. When set to
`false`, any drawing command containing a non-finite numeric value is omitted
entirely from the exported SVG.

#### Parameters
*   `bEnabled` **[boolean][29]** `true` to export malformed commands with numeric sanitization; `false` to omit malformed commands.


## setSvgClampLargeCoordinates

Sets whether very large finite SVG numeric values are clamped before export. The
default is `true`. This is a safety rail against accidentally exporting huge
coordinates or dimensions that can make SVG files unwieldy or cause problems in
downstream plotting software.

By default, values are clamped to the range `[-1000000, 1000000]`. Use
`setSvgCoordinateClampMagnitude()` to change that magnitude.

#### Parameters
*   `bEnabled` **[boolean][29]** `true` to clamp very large finite values; `false` to export them unchanged.


## setSvgCoordinateClampMagnitude

Sets the absolute magnitude used by large-coordinate clamping. The default is
`1000000`, meaning serialized numeric geometry values are clamped to the range
`[-1000000, 1000000]` when `setSvgClampLargeCoordinates(true)` is active.

#### Parameters
*   `magnitude` **[number][28]** Positive finite maximum absolute value for clamped SVG numeric geometry.



<!-- WORK IN PROGRESS; revised documentation:
## beginSvgGroup
Begins a new user-defined grouping of SVG elements.  
You may optionally provide a group name (used as the `id` attribute),  
and/or an object specifying additional attributes to apply to the group element.  
Be sure to call `endSvgGroup()` later or the SVG file will report errors.

#### Parameters
*   `gnameOrAttrs` **[string][27] | [object][26]?**  
    If a string is provided, it is used as the group name (i.e., `id` attribute).  
    If an object is provided, it is interpreted as a set of SVG attributes to apply to the group element.
*   `attrs` **[object][26]?** Optional object of additional attribute name-value pairs to apply to the group.  
    Only used if the first argument is a group name string.
-->

## beginSvgGroup

Begins a new user-defined grouping of SVG elements.
Optionally associates a group name to the SVG group.
Be sure to call `endSvgGroup()` later or the SVG file will report errors.

#### Parameters
*   `gname` **[string][27]?** Optional group name used as an ID for the SVG group.



## endSvgGroup

Ends the current user-defined group of SVG elements.


## getDefaultStrokeColor

Retrieves the default stroke color used for SVG rendering.
Returns **[string][27]**, the default stroke color (in hex, RGB, or named CSS color format).


## isRecordingSVG

Retrieves whether or not SVG recording is active.
Returns **[boolean][29]** `true` if SVG recording is active, `false` otherwise.


## Experimental Extension Hooks

p5.plotSvg intentionally exposes a few low-level hooks for advanced experiments
and companion add-ons. These hooks are not needed for ordinary SVG export, and
they may change more readily than the main public API.

During an active recording session, `p5plotSvg._commands` refers to the live
internal command array that will be converted into SVG by `endRecordSvg()`.
External code may inspect this array or append compatible command objects before
export. This interface only exists between `beginRecordSvg()` and
`endRecordSvg()`, and it is cleared after export. The read-only
`p5plotSvg.SVG_COMMAND` and `p5plotSvg.SVG_SEGMENT` constants document the
command and nested segment `type` strings used by this interface.

Related generic hooks include `injectSvgHeaderAttribute()`, `injectSvgDef()`,
custom `attributes` arrays on injected command objects, and
`setSvgExportPolylinesAsPaths()`. These make it possible to add custom
namespaces, `<defs>` entries, command-level SVG attributes, or
downstream-tool-specific path output without adding those experiments directly
to the core library.


<!-- WORK IN PROGRESS
## injectSvgHeaderAttribute  
Injects an attribute into the `<svg>` tag in the SVG header section.  
This is useful for adding custom namespaces (e.g. `xmlns:inkscape`).  
If an attribute with the same name already exists, its value will be updated rather than duplicated.

#### Parameters  
* `attrName` **[string][27]** The name of the attribute to inject (e.g. `"xmlns:inkscape"`).  
* `attrValue` **[string][27]** The value to assign to the attribute (e.g. `"http://www.inkscape.org/namespaces/inkscape"`).
-->

<!-- WORK IN PROGRESS
## injectSvgDef  
Injects a definition into the `<defs>` section of the SVG.  
Each definition is an XML element (such as `marker`) with an associated set of attributes.
If a definition with the same `type` and `id` already exists, its attributes will be updated.

#### Parameters  
* `type` **[string][27]** The tag name of the element to define (e.g. `"marker"`).
* `attributesObj` **[object][26]** An object containing name–value pairs for the attributes of the element.  
-->


[26]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object

[27]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String

[28]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number

[29]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean