@avocode/svg-exporter

SVG Exporter

Install

npm install @avocode/svg-exporter

Features

Based on Octopus 2.0 format, SVG Exporter currently is able to process the following features:

• Bitmap layers
• Group layers
• Shape layers
• Text layers [experimental support]

SVG Exporter also supports the following effects:

• Drop shadow
• Color fill
• Gradient fill (including linear and radial)
• Inner shadow
• Strokes (including inside, outside and centered)

Usage

Just import SVGExporter function from the index.js:

import SVGExporter from 'svg-exporter'

Then run this function with the following arguments:

SVGExporter(octopusLayers, options)

The first argument (octopusLayers) describes an array of Octopus 2.0 layer objects. Next argument (options) is an object containing all the global options of the SVG Exporter. At the current moment there aren't many options, but it's designed to be able to setup the process of converting with options.
Currently supported options:

• bitmaps - describes an object where key is id of bitmap layer and value is HTMLImageElement, Image, HTMLCanvasElement or Canvas object.
• postprocess - describes an object where key is name of SVG postprocessor (check list of postprocessors below) and value is object representing arguments of postprocessor. Current version of SVG Exporter doesn't have any postprocessors requiring arguments, so, it's okay to set the value of undefined for every postprocessor.
• env - the object specifies some environment descriptors, like Raven instance and so on. Passing Raven instance is possible through options.env.Raven property.
• scale - by default 1, the scale of the result SVG document.
• blendings - if true, then result SVG document will contain mix-blend-mode property on different kind of layers and effects. It's not enabled by default because blending modes aren't as exact and consistent in browser (using mix-blend-mode style property) as Sketch or PS.

Postprocessors list. All of the following are enabled by default. If there is postprocess key in the options of SVG Exporter, then only postprocessors listed in these options will be used.

• set-image-xlink - required to modify SVG output of SVGJS to make it correctly support images
• remove-svgjs-helpers - removes useless trash generated by SVGJS (happens only sometimes)
• remove-svgjs-ids-prefixes - removes SVGJS prefixes of elements' ids
• replace-xmlns - replaces :svgjs xml namespace with :avocode namespace
• shape-detect - attempts to replace <path> elements of known shapes, such as rectangles with more semantic-friendly elements such as <rect>; currently supports only detection of rectangle

Internals

The structure of the package is divided to three processing phases:

1. octopus-preprocess
2. octopus-process
3. svg-postprocess

Octopus-preprocess

The directory ./octopus-preprocess/ contains preprocessors and its manager (./octopus-preprocess/index.js). Preprocessors are used to modify and prepare input layers before SVG creation. Preprocessors doesn't depend on options of SVG Exporter. Order of preprocessors and the list of currently used ones is available at preprocessors manager (./octopus-preprocess/index.js). At the moment, the only one preprocessor is used - remove-blank-layers (it removes blank layers from input).

Octopus-process

The directory ./octopus-process/ contains all the core features of the SVG Exporter, like layer processing, effects processing and its configuration. Layers processors are separated by the layer type of Octopus 2.0 and are located at:

./octopus-process/process-layer/process-layer-bitmap/
./octopus-process/process-layer/process-layer-group/
./octopus-process/process-layer/process-layer-shape/
./octopus-process/process-layer/process-layer-text/

Effects are divided by groups. Groups are necessary for order of effects processing. The configuration of effects processing is located at ./octopus-process/config/effects-processing.js. The file contains object effectsMap describing groups of effects and responsible functions. Furthermore, effectsGroupsByLayer object represents map of effects related to the layer types and its order. Order of effects processing is set by the order of elements in array groups of each layer type and the key targetIndex which value describes the index of the target element (for example, shape). So, there are the following groups of effects:

./octopus-process/process-effects/process-effectgroup-drop-shadow
./octopus-process/process-effects/process-effectgroup-fills
./octopus-process/process-effects/process-effectgroup-inner-shadow
./octopus-process/process-effects/process-effectgroup-stroke

Each of these groups contains group processor (index.js) and files responsible for every single effect of a group.

Svg-postprocess

The directory ./svg-postprocess/ contains postprocessors of the SVG document (as a string) and its manager (./svg-postprocess/index.js). Postprocessors can be set up by options' value postprocess.

Error reporting

Error are sent to the Sentry server, it's enough to run exporter with proper environment flag in Node:

SENTRY_DSN=https://sentry-dsn-here/ node anything.js

or pass Raven instance through options.env.Raven

Tests

npm run test - lint & unit tests
npm run test-only - only unit tests

Notes

Since SVG Exporter uses SVG.js as dependency, it modifies global object (both browser's window and node's global).

Dependencies

package.json fragment:

"jsdom": "^10.1.0", // for tests only
"lodash": "^4.13.1", // used everywhere
"canvas": "^1.6.5", // when using on node, polyfill for window.Canvas
"paper": "^0.10.3", // mainly for computing shape's paths
"raven": "^1.2.1", // error reporting
"svg.js": "^2.5.1", // the SVG document assembler
"svg.filter.js": "^2.0.2", // SVG document filters
"svgdom": "^0.0.6" // when using on node, polyfill for DOM

Environment

SVG Exporter can work in both browser and node.js environments.