Keyshape File Format

Keyshape files are zip compressed files (.keyshape) or uncompressed plain text files (.keyshapex). Compressed files contain a file called document.keyshapex, which is a plain text file.

The Keyshape file format is based on SVG. SVG elements are used to represent static objects with few Keyshape specific additional attributes. Animation is described with Keyshape specific elements.

Supported SVG Features

All supported SVG features have been implemented according to the SVG 2 specification, unless otherwise noted.

Supported SVG Elements

The remark "no editing" means that the feature is supported but can not be edited with Keyshape.

Elements removed or deprecated in SVG 2 are not supported: SVG font elements, animation elements, color-profile, cursor, and tref.

New SVG 2 elements (audio, video, solidcolor, meshes, and hatches) are not supported.

Supported CSS Properties

Single id and class selectors are supported in internal CSS stylesheets. External stylesheets are not supported. The style attribute is supported.

The clip, color-profile, enable-background, glyph-orientation-horizontal, glyph-orientation-vertical, and kerning properties are deprecated in SVG 2 and are not supported.

Keyshape Elements

Keyshape defines its own elements and attributes. These elements are in the Keyshape namespace "http://ns.keyshapeapp.com".

Note: You can try some of the examples by copy-pasting them to the canvas in Keyshape.

Values used below:

• <string> is a character string, e.g., "hello.png".
• <length> is a size with a pixel unit, e.g., "100px".
• <percentage> is a percentage value, e.g., "200%".
• <number> is a number without a unit, e.g., "2".
• <color> is a color, e.g., "#ff0000" or "rgba(128, 64, 255, 1)".
• <time> is seconds, e.g., "1.210" is 1.21 seconds.
• <url> is a URL, e.g., "subpath/image.png".
• <timing-function> is a timing function, e.g., "linear", "cubic-bezier(0.1,0.2,0.8,0.7)", "steps(1, start)", built-in easing function "-ks-ease-in-quad" or custom easing function "-ks-custom('CustomEasingName')".

The first keyword value is the default value for attributes with multiple keywords. For instance, the default value for grid's display attribute (inline | none) is inline. The default value is used if the attribute is not given.

<ks:grid>

The grid element defines a grid for a document. A document can have multiple grids.

Attributes:

• color - <color> - color of the grid, can have an rgba value for transparency.
• spacing-x - <number> - x spacing of the grid in pixels.
• spacing-y - <number> - y spacing of the grid in pixels.
• display - inline | none - determines if the grid is visible or not.

Example:

<ks:grid spacing-x="15" spacing-y="20" color="rgba(255,0,0,0.30)"/>

<ks:guide>

The guide element defines a guide. A document can have multiple guides.

Attributes:

• color - <color> - color of the guide, can have an rgba value for transparency.
• transform - <transform> - transform of the guide.
• display - inline | none - determines if the guide is visible or not.

Example:

<ks:guide transform="translate(113,162) rotate(90)" color="rgba(255,0,0,0.30)" locked="locked"/>

<ks:timemarker>

The time marker element describes one time marker in the document.

Attributes:

• time - <time> - time of the marker in seconds.
• name - <string> - name of the marker.
• color - <color> - color of the marker, default value is gray (gray, blue, red,green, yellow, magenta, cyan).

Example:

<ks:timemarker name="My Marker" time="1.2" color="blue"/>

<ks:easing>

The easing element defines a custom easing curve, which can be referenced from timing functions like this: "-ks-custom('EasingName')"

Attributes:

• name - <string> - name of the custom easing curve. Characters " (0x22) and ' (0x27) are not allowed.
• function - <timing-function> - function of the custom easing curve, must not be "-ks-custom"

Example:

<ks:easing name="My Custom Easing" function="cubic-bezier(0.25, 0.4, 0.7, 0.855)"/>

<ks:animate>

This element animates an attribute or property in its parent element. Animatable properties are: transform, opacity, visibility, stroke-opacity, fill-opacity, stroke, fill, stroke-width, stroke-dasharray, stroke-dashoffset, width, height, rx, ry, d, and filter. The ks:playback property is used for symbol instance timing.

Attributes:

• attribute - name of the attribute or property to animate.
• abs-key-times - list-of-key-times - a list of key times in seconds.
• values - list-of-values - animation values.
• type - rotate | skewXY | scale | anchor - if "attribute" has value "transform", then this describes which transform type is animated.
• timing-functions - <timing-function> - a list of timing functions, one less than there are abs-key-times.
• repeat-end - <time> | indefinite - repeat end time, indefinite means repeat forever.

Example:

<rect width="20" height="10" transform="translate(20,20) translate(-10,-5)">
    <ks:animate attribute="transform" type="scale" abs-key-times="4;7.5" values="1,1;1,2"/>
    <ks:animate attribute="opacity" abs-key-times="0;3" values="1;0.5"
                timing-functions="cubic-bezier(0.42,0,0.58,1)" repeat-end="6"/>
</rect>

<ks:animateMotion>

The animateMotion element describes a motion path for its parent element. Note that orient along path (motion rotation) is an additional attribute for SVG elements. It is not part of the animateMotion element.

Attributes:

• abs-key-times - list-of-key-times - a list of key times in seconds.
• path - path-data - path data for the motion path, the first command must be a move 'M' command and the rest of the commands must be line 'L' or cubic bezier 'C' commands.
• timing-functions - <timing-function> - a list of timing functions, one less than there are abs-key-times.
• repeat-end - <time> | indefinite - repeat end time, indefinite means repeat forever.

Example:

<rect width="10" height="4" transform="translate(8,6) translate(-5,-2)" ks:motion-rotation="auto">
    <ks:animateMotion abs-key-times="0;2;5" path="M8,6L19,16L19,25"
                      timing-functions="cubic-bezier(0,0,0.58,1);linear"/>
</rect>

<ks:export>

The export element defines export values. Only the first export element is used.

If the animation attribute is "none", then the frame at zero time is exported.

Attributes:

• filename - <string> - the name of the exported file, # signs are replaced with a frame number in image sequences.
• width - <length> | percentage> - width of the exported image, only for bitmap images.
• height - <length> | <percentage> - height of the exported image, only for bitmap images.
• size-aspect-ratio - locked | unlocked - locked will maintain document aspect ratio in export dialog.
• format - svg | svgz | png | jpeg | webp | animated-gif | mpeg-4 - file format to export.
• animation - none | css | keyshapejs | animated | sequence | sprite-sheet - "css" and "keyshapejs" are valid only for svg file formats. "animated" is valid only for PNG and WebP formats.
• text-output - normal | paths - text output method, "paths" converts text to paths, only for the svg file formats.
• embed - none | images - the value "images" embeds all images, only for the svg file formats.
• loop-count - <number> - animation loop count, 0=forever, only for animated gifs and svgs.
• quality - <number> | lossless - quality for JPEG and WebP formats.
• dither - ordered | diffusion | none - dither mode for animated GIFs.
• transparency - disabled | enabled - transparency for animated GIFs.
• css-motion-path - offset-path | transform - writes offset-path or transform attributes for CSS animations.
• filter-output - css | svg - writes CSS or SVG filters to SVG files.
• id-output - normal | unique | minimal | prefix str - id output method for SVG files.
• scriptsrc - embed | external | url() - Exported KeyshapeJS JavaScript library location: embedded, external or custom URL.
• optimize-svg - enabled | decimals(n) | disable-remove-indentation | disable-remove-xml-instr | disable-remove-comments | disable-merge-groups | disable-remove-unused-resources | disable-remove-empty-objects | disable-remove-hidden-objects | disable-remove-unused-ids | disable-remove-unnecessary-properties | disable-shorten-property-values - optimization flags for SVG files, specific optimizations can be disabled.

Attributes for animated-gif, mpeg-4, sequence and sprite-sheet formats:

• begin-time - auto | <time> - the first frame to export, the value "auto" uses document's play range.
• end-time - auto | <time> - the last frame to export, the value "auto" uses document's play range.
• fps - auto | <number> - the frame rate for export (1-100), the value "auto" uses document's frame rate.

Attributes for sprite sheets:

• sheet-algorithm - row | column | grid - algorithm to fill in the sprite sheet.
• sheet-width - <number> - width of the sprite sheet if sheet-algorithm is "grid".
• sheet-height - <number> - height of the sprite sheet if sheet-algorithm is "grid".

Examples:

<ks:export filename="hello.svg" format="svg" animation="css" text-output="paths"/>

<ks:export filename="hello-####.png" format="png" width="200%" height="200%"
           animation="sequence" begin-time="1" end-time="3.5"/>

<ks:palette>

The palette element contains swatches for the document. The palette element must be a child of the root SVG element.

Attributes: none.

<ks:swatch>

The swatch element defines a swatch for the document and must be under the palette element.

The swatch can be referenced from fill or stroke attributes like this: "-ks-swatch('Swatch-Name' userSpaceOnUse l 0 -18.5 0 18.5 r 48.5 0 0 0 0 pad matrix(1 0 0 1 0 0))". The values after "l" define coordinates for linear gradients and after "r" define coordinates for radial gradients. "pad" and "matrix()" are gradient repeat and transform parameters.

Attributes:

• name - <string> - the name of the swatch
• type - none | color | linear-gradient | radial-gradient - the swatch type
• value - <string> - the color value or gradient stop values

Example:

<ks:palette>
    <ks:swatch name="Swatch-X" type="none"/>
    <ks:swatch name="Swatch-1" type="color" value="#c06e6e"/>
    <ks:swatch name="AlphaSwatch" type="color" value="rgba(51,12,190,0.73)"/>
    <ks:swatch name="LinearGrad" type="linear-gradient" value="#ffffff 0%, #b5ff24 28.5%, rgba(51,12,190,0.37) 100%"/>
    <ks:swatch name="MyRadGradient" type="radial-gradient" value="rgba(0, 255, 0, 0.50) 0%, #000000 100%"/>
</ks:palette>
<ellipse rx="30" ry="30" fill="-ks-swatch('MyRadGradient' userSpaceOnUse l 0 -33 0 33 r 33 0 0 0 0 pad matrix(1 0 0 1 0 0))" stroke-width="10" transform="translate(100,10)"/>

<ks:resource>

The resource element indicates a linked image. This element is used if an image is added to the document's resources, but it is not present on the document canvas.

Attributes:

• href - <url> - an absolute or relative file URL to a file.

Example:

<ks:resource href="my-image.png"/>

Additional attributes for SVG elements

The following SVG elements can have additional attributes.

The root <svg> element

• ks:grid-visibility - visible | hidden - "visible" to show all visible grids.
• ks:guide-visibility - visible | hidden - "visible" to show all visible guides.
• ks:fps - document's frames per second value.
• ks:preview - svg/keyshapejs | svg/css - preview format.
• ks:transparency - <color> [<color>] - a solid color or checkerboard pattern to indicate transparency.
• ks:playRangeIn - <time> - play range start time in milliseconds.
• ks:playRangeOut - <time> | auto | last-keyframe | infinity - play range end time in milliseconds. The 'last-keyframe' value is deprecated.
• ks:timeDisplay - seconds | timecode | frames - time display format.
• ks:startFrame - <number> - start frame number.
• ks:version - always 1.1. The version 1.0 is not used anymore.
• ks:trigger - onload | onclick | onpointerenter | onscrollintoview | none - a space separated list of animation start events.
• ks:trigger-restart - never | always | when-finished - restart options.
• ks:defaultEasing - <string> - the name of the document's default easing.

The <g> element

• ks:type - normal | layer - if the value is "layer", then the group element acts as a layer.

The <script> element

• ks:script-location - normal | end - if the value is "end", then the script element is always exported as the last element of the document.

Transformable objects (rect, ellipse, path, text, image, g)

• ks:motion-rotation - none | auto - the value "auto" makes the element rotate along a motion path.

All elements

• ks:locked - none | locked - the value "locked" makes the element locked for selections and Object Tree shows a lock symbol.
• ks:expand-tree - expanded | collapsed - for container objects, the value "collapsed" means that the Object Tree is collapsed.

Additional information in SVG path data

SVG path data can store information about the node's type. The node type is determined from the last coordinate of a move (M) or cubic bezier (C) path command. If the x coordinate is prepended with a zero, then the node is a symmetric node. If the y coordinate is prepended with a zero, then the node is an asymmetric node.

Here's an example with three nodes, the second node is a symmetric node and the third one is an asymmetric node.

<path d="M0,0C0,0,2,2,04,2C6,2,7,1,9,00"/>

Fonts

Keyshape stores the PostScript font name of the font so that the font can be uniquely identified and to make it compatible with other vector graphics software.