SVG (Scalable Vector Graphics) is an XML format for specifying images. SVG images support the following additional image descriptor properties:
:foreground foregroundforeground, if non-nil, should be a string specifying a
color, which is used as the image’s foreground color. If the value is
nil, it defaults to the current face’s foreground color.
:background backgroundbackground, if non-nil, should be a string specifying a
color, which is used as the image’s background color if the image
supports transparency. If the value is nil, it defaults to the
current face’s background color.
:css csscss, if non-nil, should be a string specifying the CSS to
override the default CSS used when generating the image.
If your Emacs build has SVG support, you can create and manipulate these images with the following functions from the svg.el library.
Create a new, empty SVG image with the specified dimensions. args is an argument plist with you can specify following:
:stroke-widthThe default width (in pixels) of any lines created.
:strokeThe default stroke color on any lines created.
This function returns an SVG object, a Lisp data structure that specifies an SVG image, and all the following functions work on that structure. The argument svg in the following functions specifies such an SVG object.
Create a gradient in svg with identifier id. type
specifies the gradient type, and can be either linear or
radial. stops is a list of percentage/color pairs.
The following will create a linear gradient that goes from red at the start, to green 25% of the way, to blue at the end:
(svg-gradient svg "gradient1" 'linear
'((0 . "red") (25 . "green") (100 . "blue")))
The gradient created (and inserted into the SVG object) can later be used by all functions that create shapes.
All the following functions take an optional list of keyword parameters that alter the various attributes from their default values. Valid attributes include:
:stroke-widthThe width (in pixels) of lines drawn, and outlines around solid shapes.
:stroke-colorThe color of lines drawn, and outlines around solid shapes.
:fill-colorThe color used for solid shapes.
:idThe identified of the shape.
:gradientIf given, this should be the identifier of a previously defined gradient object.
:clip-pathIdentifier of a clip path.
Add to svg a rectangle whose upper left corner is at position x/y and whose size is width/height.
(svg-rectangle svg 100 100 500 500 :gradient "gradient1")
Add to svg a circle whose center is at x/y and whose radius is radius.
Add to svg an ellipse whose center is at x/y, and whose horizontal radius is x-radius and the vertical radius is y-radius.
Add to svg a line that starts at x1/y1 and extends to x2/y2.
Add to svg a multiple-segment line (a.k.a. “polyline”) that goes through points, which is a list of X/Y position pairs.
(svg-polyline svg '((200 . 100) (500 . 450) (80 . 100))
:stroke-color "green")
Add a polygon to svg where points is a list of X/Y pairs that describe the outer circumference of the polygon.
(svg-polygon svg '((100 . 100) (200 . 150) (150 . 90))
:stroke-color "blue" :fill-color "red")
Add the outline of a shape to svg according to commands, see SVG Path Commands.
Coordinates by default are absolute. To use coordinates relative to
the last position, or – initially – to the origin, set the attribute
:relative to t. This attribute can be specified for the
function or for individual commands. If specified for the function,
then all commands use relative coordinates by default. To make an
individual command use absolute coordinates, set :relative to
nil.
(svg-path svg '((moveto ((100 . 100))) (lineto ((200 . 0) (0 . 200) (-200 . 0))) (lineto ((100 . 100)) :relative nil)) :stroke-color "blue" :fill-color "lightblue" :relative t)
Add the specified text to svg.
(svg-text svg "This is a text" :font-size "40" :font-weight "bold" :stroke "black" :fill "white" :font-family "impact" :letter-spacing "4pt" :x 300 :y 400 :stroke-width 1)
Add an embedded (raster) image to svg. If datap is
nil, image should be a file name; otherwise it should be a
string containing the image data as raw bytes. image-type should be a
MIME image type, for instance "image/jpeg".
(svg-embed svg "~/rms.jpg" "image/jpeg" nil
:width "100px" :height "100px"
:x "50px" :y "75px")
To svg add an embedded (raster) image placed at
relative-filename. relative-filename is searched inside
file-name-directory of the :base-uri svg image property.
:base-uri specifies a (possibly non-existing) file name of the
svg image to be created, thus all the embedded files are searched
relatively to the :base-uri filename’s directory. If
:base-uri is omitted, then filename from where svg image is
loaded is used. Using :base-uri improves the performance of
embedding large images, comparing to svg-embed, because all the
work is done directly by librsvg.
;; Embedding /tmp/subdir/rms.jpg and /tmp/another/rms.jpg
(svg-embed-base-uri-image svg "subdir/rms.jpg"
:width "100px" :height "100px"
:x "50px" :y "75px")
(svg-embed-base-uri-image svg "another/rms.jpg"
:width "100px" :height "100px"
:x "75px" :y "50px")
(svg-image svg :scale 1.0
:base-uri "/tmp/dummy"
:width 175 :height 175)
Add a clipping path to svg. If applied to a shape via the :clip-path property, parts of that shape which lie outside of the clipping path are not drawn.
(let ((clip-path (svg-clip-path svg :id "foo")))
(svg-circle clip-path 200 200 175))
(svg-rectangle svg 50 50 300 300
:fill-color "red"
:clip-path "url(#foo)")
Add the custom node tag to svg.
(svg-node svg
'rect
:width 300 :height 200 :x 50 :y 100 :fill-color "green")
Remove the element with identifier id from the svg.
Finally, the svg-image takes an SVG object as its argument and
returns an image object suitable for use in functions like
insert-image.
Here’s a complete example that creates and inserts an image with a circle:
(let ((svg (svg-create 400 400 :stroke-width 10)))
(svg-gradient svg "gradient1" 'linear '((0 . "red") (100 . "blue")))
(svg-circle svg 200 200 100 :gradient "gradient1"
:stroke-color "green")
(insert-image (svg-image svg)))
SVG paths allow creation of complex images by combining lines, curves, arcs, and other basic shapes. The functions described below allow invoking SVG path commands from a Lisp program.
Move the pen to the first point in points. Additional points
are connected with lines. points is a list of X/Y coordinate
pairs. Subsequent moveto commands represent the start of a
new subpath.
(svg-path svg '((moveto ((200 . 100) (100 . 200) (0 . 100))))
:fill "white" :stroke "black")
End the current subpath by connecting it back to its initial point. A line is drawn along the connection.
(svg-path svg '((moveto ((200 . 100) (100 . 200) (0 . 100)))
(closepath)
(moveto ((75 . 125) (100 . 150) (125 . 125)))
(closepath))
:fill "red" :stroke "black")
Draw a line from the current point to the first element in points, a list of X/Y position pairs. If more than one point is specified, draw a polyline.
(svg-path svg '((moveto ((200 . 100)))
(lineto ((100 . 200) (0 . 100))))
:fill "yellow" :stroke "red")
Draw a horizontal line from the current point to the first element in x-coordinates. Specifying multiple coordinates is possible, although this usually doesn’t make sense.
(svg-path svg '((moveto ((100 . 200)))
(horizontal-lineto (300)))
:stroke "green")
Draw vertical lines.
(svg-path svg '((moveto ((200 . 100)))
(vertical-lineto (300)))
:stroke "green")
Using the first element in coordinate-sets, draw a cubic Bézier
curve from the current point. If there are multiple coordinate sets,
draw a polybezier. Each coordinate set is a list of the form
(x1 y1 x2 y2 x y), where
(x, y) is the curve’s end point. (x1, y1) and (x2, y2) are control points at the
beginning and at the end, respectively.
(svg-path svg '((moveto ((100 . 100)))
(curveto ((200 100 100 200 200 200)
(300 200 0 100 100 100))))
:fill "transparent" :stroke "red")
Using the first element in coordinate-sets, draw a cubic Bézier
curve from the current point. If there are multiple coordinate sets,
draw a polybezier. Each coordinate set is a list of the form
(x2 y2 x y), where (x, y) is the curve’s end point and (x2, y2) is the
corresponding control point. The first control point is the
reflection of the second control point of the previous command
relative to the current point, if that command was curveto
or smooth-curveto. Otherwise the first control point
coincides with the current point.
(svg-path svg '((moveto ((100 . 100)))
(curveto ((200 100 100 200 200 200)))
(smooth-curveto ((0 100 100 100))))
:fill "transparent" :stroke "blue")
Using the first element in coordinate-sets, draw a quadratic
Bézier curve from the current point. If there are multiple coordinate
sets, draw a polybezier. Each coordinate set is a list of the form
(x1 y1 x y), where (x, y) is the curve’s end point and (x1, y1) is the
control point.
(svg-path svg '((moveto ((200 . 100)))
(quadratic-bezier-curveto ((300 100 300 200)))
(quadratic-bezier-curveto ((300 300 200 300)))
(quadratic-bezier-curveto ((100 300 100 200)))
(quadratic-bezier-curveto ((100 100 200 100))))
:fill "transparent" :stroke "pink")
Using the first element in coordinate-sets, draw a quadratic
Bézier curve from the current point. If there are multiple coordinate
sets, draw a polybezier. Each coordinate set is a list of the form
(x y), where (x, y) is the curve’s
end point. The control point is the reflection of the control point
of the previous command relative to the current point, if that command
was quadratic-bezier-curveto or
smooth-quadratic-bezier-curveto. Otherwise the control
point coincides with the current point.
(svg-path svg '((moveto ((200 . 100)))
(quadratic-bezier-curveto ((300 100 300 200)))
(smooth-quadratic-bezier-curveto ((200 300)))
(smooth-quadratic-bezier-curveto ((100 200)))
(smooth-quadratic-bezier-curveto ((200 100))))
:fill "transparent" :stroke "lightblue")
Using the first element in coordinate-sets, draw an elliptical
arc from the current point. If there are multiple coordinate sets,
draw a sequence of elliptical arcs. Each coordinate set is a list of
the form (rx ry x y), where
(x, y) is the end point of the ellipse, and
(rx, ry) are its radii. Attributes may be appended to
the list:
:x-axis-rotationThe angle in degrees by which the x-axis of the ellipse is rotated relative to the x-axis of the current coordinate system.
:large-arcIf set to t, draw an arc sweep greater than or equal to 180
degrees. Otherwise, draw an arc sweep smaller than or equal to 180
degrees.
:sweepIf set to t, draw an arc in positive angle direction.
Otherwise, draw it in negative angle direction.
(svg-path svg '((moveto ((200 . 250)))
(elliptical-arc ((75 75 200 350))))
:fill "transparent" :stroke "red")
(svg-path svg '((moveto ((200 . 250)))
(elliptical-arc ((75 75 200 350 :large-arc t))))
:fill "transparent" :stroke "green")
(svg-path svg '((moveto ((200 . 250)))
(elliptical-arc ((75 75 200 350 :sweep t))))
:fill "transparent" :stroke "blue")
(svg-path svg '((moveto ((200 . 250)))
(elliptical-arc ((75 75 200 350 :large-arc t
:sweep t))))
:fill "transparent" :stroke "gray")
(svg-path svg '((moveto ((160 . 100)))
(elliptical-arc ((40 100 80 0)))
(elliptical-arc ((40 100 -40 -70
:x-axis-rotation -120)))
(elliptical-arc ((40 100 -40 70
:x-axis-rotation -240))))
:stroke "pink" :fill "lightblue"
:relative t)