startautomating / pssvg

Script SVGs with PowerShell

PowerShell tools for SVG.

PSSVG helps you create Scalable Vector Graphics using PowerShell.

There is a command for every tag of the SVG standard (and then some).

For example, this script generates the image below it.

svg (
    svg.text -X 50% -Y 50% -Fontsize 36 "Hello World" -DominantBaseline middle -TextAnchor middle -Fill '#4488ff'
) -ViewBox 0,0, 200, 100

PSSVG has a lot cooler Examples than hello world:

Example Name	Image
Animate	Animate.svg
AnimateColor	AnimateColor.svg
AnimatedShapes	AnimatedShapes.svg
AnimateMotion	AnimateMotion.svg
Blur	Blur.svg
BPMAnimate	BPMAnimate.svg
BPMMorph	BPMMorph.svg
BPMTriangleMorph	BPMTriangleMorph.svg
Circles	Circles.svg
CloudAnimation	CloudAnimation.svg
Clouds	Clouds.svg
DropShadow	DropShadow.svg
Embossed	Embossed.svg
FadeIn	FadeIn.svg
HelloWorld	HelloWorld.svg
HexagonPattern	HexagonPattern.svg
Index	Index.svg
LinearGradient	LinearGradient.svg
LinearGradientAnimated	LinearGradientAnimated.svg
ManyAnimatedRectangles	ManyAnimatedRectangles.svg
ManyRectangles	ManyRectangles.svg
Morphing	Morphing.svg
MovingGradient	MovingGradient.svg
MovingShadows
Pattern	Pattern.svg
PatternAnimation	PatternAnimation.svg
PatternMask	PatternMask.svg
PowerShellChevron	PowerShellChevron.svg
RadialGradient	RadialGradient.svg
RadialGradientAnimated	RadialGradientAnimated.svg
RepeatedShapes	RepeatedShapes3.svg RepeatedShapes4.svg RepeatedShapes5.svg RepeatedShapes6.svg
Shapes	Shapes.svg
SpinningSpiral	SpinningSpiral15.svg SpinningSpiral636.svg SpinningSpiral741.svg SpinningSpiral901.svg
StarRating	StarRating.svg
Stars	Stars.svg Stars10.svg Stars11.svg Stars12.svg Stars5.svg Stars6.svg Stars7.svg Stars8.svg Stars9.svg
StartAutomating	StartAutomating.svg
StopUsingGIFs	StopUsingGIFs.svg
SweepCircle	SweepCircle.svg
US-Flag	US-Flag.svg
US-FlagAnimated	US-FlagAnimated.svg
VerticalLinearGradient	VerticalLinearGradient.svg
ViewBoxAnimation	ViewBoxAnimation.svg

PSSVG is designed to act as a fairly complete domain specific language: every aspect of the SVG standard should be reflected in the commands of PSSVG.

The following commands are supported:

Element	Function	Aliases
a	SVG.a	=<svg.a>
animate	SVG.animate	=<svg.animate>
animateMotion	SVG.animateMotion	=<svg.animateMotion>
animateTransform	SVG.animateTransform	=<svg.animateTransform>
ANSI	SVG.ANSI	=<svg.ANSI>
ArcPath	SVG.ArcPath	=<SVG.ArcedPath> =<svg.ArcPath> SVG.ArcedPath
circle	SVG.circle	=<svg.circle>
clipPath	SVG.clipPath	=<svg.clipPath>
ConvexPolygon	SVG.ConvexPolygon	=<svg.ConvexPolygon> SVG.Decagon SVG.Dodecagon SVG.Enneadecagon SVG.Hendecagon SVG.Heptadecagon SVG.Heptagon SVG.Hexadecagon SVG.Hexagon SVG.Icosagon SVG.Icosikaidigon SVG.Icosikaienneagon SVG.Icosikaihenagon SVG.Icosikaiheptagon SVG.Icosikaihexagon SVG.Icosikaioctagon SVG.Icosikaipentagon SVG.Icositetragon SVG.Icositrigon SVG.Nonagon SVG.Octadecagon SVG.Octagon SVG.Pentadecagon SVG.Pentagon SVG.Tetradecagon SVG.Triacontagon SVG.Tridecagon
CurvePath	SVG.CurvePath	=<SVG.CurvedPath> =<svg.CurvePath> SVG.CurvedPath
defs	SVG.defs	=<svg.defs>
desc	SVG.desc	=<svg.desc>
discard	SVG.discard	=<svg.discard>
DropShadow	SVG.DropShadow	=<svg.DropShadow>
ellipse	SVG.ellipse	=<svg.ellipse>
feBlend	SVG.feBlend	=<svg.feBlend>
feColorMatrix	SVG.feColorMatrix	=<svg.feColorMatrix>
feComponentTransfer	SVG.feComponentTransfer	=<svg.feComponentTransfer>
feComposite	SVG.feComposite	=<svg.feComposite>
feConvolveMatrix	SVG.feConvolveMatrix	=<svg.feConvolveMatrix>
feDiffuseLighting	SVG.feDiffuseLighting	=<svg.feDiffuseLighting>
feDisplacementMap	SVG.feDisplacementMap	=<svg.feDisplacementMap>
feDistantLight	SVG.feDistantLight	=<svg.feDistantLight>
feDropShadow	SVG.feDropShadow	=<svg.feDropShadow>
feFlood	SVG.feFlood	=<svg.feFlood>
feFuncA	SVG.feFuncA	=<svg.feFuncA>
feFuncB	SVG.feFuncB	=<svg.feFuncB>
feFuncG	SVG.feFuncG	=<svg.feFuncG>
feFuncR	SVG.feFuncR	=<svg.feFuncR>
feGaussianBlur	SVG.feGaussianBlur	=<svg.feGaussianBlur>
feImage	SVG.feImage	=<svg.feImage>
feMerge	SVG.feMerge	=<svg.feMerge>
feMergeNode	SVG.feMergeNode	=<svg.feMergeNode>
feMorphology	SVG.feMorphology	=<svg.feMorphology>
feOffset	SVG.feOffset	=<svg.feOffset>
fePointLight	SVG.fePointLight	=<svg.fePointLight>
feSpecularLighting	SVG.feSpecularLighting	=<svg.feSpecularLighting>
feSpotLight	SVG.feSpotLight	=<svg.feSpotLight>
feTile	SVG.feTile	=<svg.feTile>
feTurbulence	SVG.feTurbulence	=<svg.feTurbulence>
filter	SVG.filter	=<svg.filter>
foreignObject	SVG.foreignObject	=<svg.foreignObject>
g	SVG.g	=<svg.g>
GoogleFont	SVG.GoogleFont	=<svg.GoogleFont>
image	SVG.image	=<svg.image>
Kite	SVG.Kite	=<svg.Kite> SVG.Rhombuses
line	SVG.line	=<svg.line>
linearGradient	SVG.linearGradient	=<svg.linearGradient>
LinePath	SVG.LinePath	=<SVG.LinedPath> =<svg.LinePath> SVG.LinedPath
marker	SVG.marker	=<svg.marker>
mask	SVG.mask	=<svg.mask>
metadata	SVG.metadata	=<svg.metadata>
mpath	SVG.mpath	=<svg.mpath>
path	SVG.path	=<svg.path>
pattern	SVG.pattern	=<svg.pattern>
polygon	SVG.polygon	=<svg.polygon>
polyline	SVG.polyline	=<svg.polyline>
radialGradient	SVG.radialGradient	=<svg.radialGradient>
rect	SVG.rect	=<svg.rect>
Rhombus	SVG.Rhombus	=<svg.Rhombus> SVG.Rhombi
script	SVG.script	=<svg.script>
set	SVG.set	=<svg.set>
Spiral	SVG.Spiral	=<svg.Spiral>
Star	SVG.Star	=<svg.Star>
stop	SVG.stop	=<svg.stop>
style	SVG.style	=<svg.style>
StyleSheet	SVG.StyleSheet	=<svg.StyleSheet>
svg	SVG.svg	=<svg> svg
switch	SVG.switch	=<svg.switch>
symbol	SVG.symbol	=<svg.symbol>
text	SVG.text	=<svg.text>
textPath	SVG.textPath	=<svg.textPath>
title	SVG.title	=<svg.title>
Triangle	SVG.Triangle	=<svg.Triangle>
tspan	SVG.tspan	=<svg.tspan>
use	SVG.use	=<svg.use>
view	SVG.view	=<svg.view>

(elements marked deprecated are not supported)

Goals

PSSVG hopes to be a useful toolkit for generating SVG images from PowerShell.

SVG has many benefits as an image file format, for example:

• File Size
• Scalability
• Animations
• Clickability
• HTML/JavaScript/CSS integration
• OS Integration

However, it is not a complete programming language.

Thus the primary goal is to make SVG creation scriptable.

Limitations

At current, PSSVG does not support aria attributes. Events can be generically specified with the parameter -On.

How PSSVG is Built

In order to provide an ideal PowerShell experience with rich help,
PSSVG is currently built by reading the contents of the Mozilla Developer Network's content repository.

It uses two PowerShell modules to read the repository and create the commands:

• Irregular is used to help parse the markdown contents of the repository
• PipeScript is used to create the functions from the parsed data.

pssvg's Issues

PSSVG should have a workflow

Include example of BPM Animation

Splatting and simple math can make for musically synchonized animations.

Include an example that generates a pattern that repeats based off of a beat.

Building PSSVGs logo with PSSVG

Add an -Attribute parameter to all SVG.* generated functions

This prevents any limitations of the generator from stopping implementation of newer features.

PSSVG should include it's generator

Self-host action

As PSSVG has an action, it should use this to build it's examples

PSSVG should include SVG.Triangle

This should inherit from SVG.Polygon.

PSSVG should include an example of SVG moprhing

This is a nifty capability to be able to morph a polygon from one shape into another.

Add SVG.DropShadow

SVG.DropShadow should inherit from SVG.Filter.

PSSVG should have examples

Introducing PSSVG

PSSVG is a PowerShell Module for scalable vector graphics. It allows you to build SVG elements using simple PowerShell functions, and it has a function for every element in the SVG standard.

PSSVG

Moving Gradient Example should move the whole way around

This would help demonstrate sequential animation (and look cool)

PSSVG should start creating custom commands

Now that PipeScript allows us to inherit functions, we can start creating custom commands that output SVG elements and otherwise act like an SVG element.

These commands should exist beneath /Commands/Custom.

Initial suggestions include:

• #43 (inherits from SVG.filter)
• #42 (inherits from SVG.Path)

PSSVG action should run all .PSSVG files

It currently attempts to run a non-existent command.

Some examples incorrectly use #require

Attributes with many sets of metadata present problems in generation.

Some SVG attributes have multiple property tables, with different valid values for different elements.

This presents a bit of a blocking problem, since this presents all but the first alphabetical element from having the correct set of attributes.

To work around this, we will need to parse multiple tables and associate them with the elements they apply to.

PSSVG should use the PowerShell Chevron in it's logo

PSSVG should correct markdown links

Because PSSVG is built atop of MDN's documentation, it contains various markdown links that would become invalid.

They can be corrected by linking to developer.mozilla.org.

Examples directory should have a README preview

This should be done with PipeScript and a README.ps1.md

Making a Visual Leitmotif for PowerShell with PSSVG

Because Start-Automating is a PowerShell shop, we have to make a lot of logos that visually hint at the relation between this project on PowerShell.

Doing this consistently across projects is a big benefit of building your assets with scripts. Essentially, what we can do is create a reusable part of a design and reuse that part in project after project.

I call this sort of technique a "Visual Leitmotif" (a Leitmotif is a recurrent theme throughout a composition).

The SVG standard provides something that can make this a little easier, a Symbol.

Using PSSVG, we can create our Visual Leitmotif with just a few lines of code.

=<svg> -ViewBox 100,100 -Content @(
    =<svg.symbol> -Id psChevron -Content @(
        =<svg.polygon> -Points (@(
            "40,20"
            "45,20"
            "60,50"
            "35,80"
            "32.5,80"
            "55,50"
        ) -join ' ')
    ) -ViewBox 100, 100

    =<svg.use> -Href '#psChevron' -Fill '#4488ff'
)

The above code produces this little nifty graphic:

That's a nifty little image we can use again and again.

---

Here's the ScriptDeck logo, which makes pretty prominent use of the PowerShell Chevron:

---

Here it is again in the GitPub logo:

---

And again in the ugit logo:

---

And again in PSDevOps PSDevOps logo:

---

And, of course, in an updated PSSVG logo:

---

As a design technique, visual leitmotifs are a great way to remind people of a central brand without drawing too much attention to it.

With scripting, it's easy to establish that visual leitmotif and reuse it moving forward.

Just get it right once and include or copy and paste between project to project.

Hope this Helps

SVG functions should include examples

Since the /Examples directory contains a number of examples, any given function could include the contents files that reference that command as examples.

Scripting Existing SVGs with ConvertTo-PSSVG

ConvertTo-PSSVG

PSSVG would be much more useful if it could easily convert any SVG off of the internet into a PSSVG file.

So, as of PSSVG 0.2.4, you can ConvertTo-PSSVG

What it does

ConvertTo-PSSVG takes an SVG from a file, url, string, or xml document and converts it into a PSSVG script.

For example, if I download the feather icon for anchor and then run

ConvertTo-PSSVG Anchor.svg

It will output:

=<SVG> -width '24' -height '24' -viewBox '0 0 24 24' -fill 'none' -stroke 'currentColor' -strokewidth '2' -strokelinecap 'round' -strokelinejoin 'round' -class 'feather feather-anchor' -Content @(
    =<SVG.circle> -cx '12' -cy '5' -r '3'
    =<SVG.line> -x1 '12' -y1 '22' -x2 '12' -y2 '8'
    =<SVG.path> -d 'M5 12H2a10 10 0 0 0 20 0h-3'
)

How it works

This is actually fairly trivial.

First we get the XML form of the input, then we:

1. Go thru to the first node
2. Replace text nodes with their text.
3. Find the appropriate command
4. Replace attributes with parameters (if found)
5. Replace child nodes recursively (effectively goto step 1).

For bonus points, we indent.

What we can do with this

Being able to ConvertTo-PSSVG gives you an easy way to integrate any existing design into your scripts. This can help, say, establish a visual leitmotif.

Hope this Helps

ConvertTo-PSSVG should try to handle slightly malformed XML.

As ConvertTo-PSSVG doesn't control the whole internet, it's important we handle the unexpected.

Thus:

When ConvertTo-PSSVG attempts to reach a RESTful URL and it receives a string, it should:

1. Trim any leading content before the first tag
2. Attempt to coerce it to XML.

PSSVG should support -Data attributes

Each SVG command should support a -Data parameter, which will be used to populate data attributes

Write-SVG should output objects

In order to improve the module experience and make PSSVG more useful, one should be able to use the elements created at each step as objects.

These objects should be decorated to allow for formatting.

All SVG functions should .Link to Write-SVG

Write-SVG should allow -Viewbox to only provide width and height

SVG.DropShould should use SVG.feDropShadow

PSSVG should automatically document

PSSVG should use HelpOut to create automatic documentation.

PSSVG should be usable as a GitHub action

Add an example of "Sweeping" a Circle

Make a line in the center and a circle, and rotate the line around that center point.

Examples should standardize fill

Not all examples have a standardized fill, which makes them more difficult to see depending on the color scheme.

Add example of SVG.feGaussianBlur

Filtering effects are cool, and need more examples.

PSSVG should use GitPub for microblogging.

Remove codename references

Some files still contain references to the development name of this module.

Write-SVG -OutputPath should prettify XML.

SVG.Element should have a formatter

SVG.Elements should have a formatter.

A very ideal version of this would show colorized XML for the SVG content.

Luckily, EZOut already has one. We should be able to make some minor modifications to this to produce an ideal experience.

Elements should always allow tags as -Content

Even when the standard indicates that the content will be text, there are scenarios where the content should be text and elements.

Thus -Content should be escaped if it does not start with a tag, and all -Content parameters should be untyped.

PSSVG Should Generate Files into a Subfolder

This will make the repository easier to navigate.

SVG functions should link to PSSVG docs and MDN

PSSVG should include Write-SVG

Write-SVG should be the core function other SVG functions call (to save disk space)

PSSVG should have a github page

It should be mapped to PSSVG.start-automating.com

PSSVG should have tests

Write-SVG should coerce [Timespan]s into the desired format.

This may need improvement later, if interval formats are used anywhere.

However, for the common case (-dur/-duration), being able to simply use a [Timespan]'s .TotalSeconds would do.

Build Script should include argumentcompleters

In some cases, there are several fixed arguments and one or more types of input (for instance, with -FontWeight).

Making the best PowerShell experience for these parameters requires making an ArgumentCompleter.

Expand Example Coverage

Now that examples are automatically included (#16), it's important to expand coverage of the examples so that more commands have them.

Write-SVG should move into Commands/Common

Add SVG.Spiral

SVG.Spiral should inherit from SVG.Path and create a spiral.

It should exclude the parameters: D, Fill

Fill should always be transparent.

README tag names should be escaped.

This will assist site generation.

PSSVG workflow build should run sequentially

It is currently in a series of jobs, which is more likely to cause conflicts.