SVG::VCD::Format - format of .vcd (vertebral column description) files
*width: 800 *height: 565 Taxon: Apatosaurus louisae Specimen: CM 3018 Citation: Gilmore 1936:195 and plates 24-25 Data: -----YVVVVVVVVV|VVVuuunnn-
Vertebral Column Description (VCD) format is line-oriented. Each line has a self-contained meaning.
Comments are introduced by a hash character (#) and run to the end of the line. They are ignored.
#
Leading and trailing whitespace are ignored.
Blank lines (including those consisting only of spaces and/or comments) ignored.
All other lines fall into one of two categories:
These lines begin with an asterisk (*). Each such line is of the form *property: value. It sets the named property to the specified value. Valid properties and their meanings are described below.
*
:
All other lines are data. Each such line is of the form property: value with no leading asterisk. It provides data about a specific taxon in the vertebral column diagram. Data is described in detail below.
Lines that do not match of either of these forms are invalid.
Taxon
Specifies the name of a taxon which will appear in the diagram. The data for each taxon begins with a Taxon line. Following this, any or all of the other three data lines may follow in any order.
Specimen
Indicates the specimen number of the individual that is described. Useful when multiple individuals of the same taxon are included.
Citation
Specifies the source of the observations in the Data line: typically either a citation of a published descriptive paper, or "personal observation". At present, this is not used: the intention is that a future version of vcd2svg will included it in an auto-generated caption.
Data
Specifies the information about the individual vertebrae of the column in question. The state of each vertebra is specified by a single character, which can be anything at all. The way those states are illustrated depends on how they are described by the state-char-color and state-char-polygon configuration settings described below. These can be configured in such as way as to represent cervicals vs. dorsals, pneumatic vs. apneumatic vertebrae, bifid vs. simple neural spines, or whatever other characteristic is of interest.
state-
-color
-polygon
Two character in the data is special:
First, the hyphen (-) indicates that no data is available for the vertebra in question, so nothing is drawn.
-
Second, the vertical bar (|) indicates the anchor point: a position within the vertebral column that is particular interest, such as the cervicodorsal transition, or the dorsosacral transition. The anchor points of all the vertebral columns will be horizontally aligned in the output.
|
For consistency, in the configuration settings below this anchor point is always referred to as the "cervico-dorsal" transition, the vertebrae before it are referred to as "cervicals" and those after it as "dorsals". But since these terms do not appear in the output, the anchor point may be used as a different transition.
Each of these properties has a single global setting, which applies across all taxa in the diagram. If a setting is set for a second time, the new value replaces the old.
The following settings are recognised:
background
If specified, then the emitted SVG file has a solid background in the specified colour; otherwise, it is transparent.
The value can be any string that is interpreted as identifying a color in SVG -- for example, a name such as red or an RGB triple such as rgb(0,193,252). See http://www.w3.org/TR/SVG11/types.html#Color
red
rgb(0,193,252)
box-color
grey
The color of the boxes that outline each vertebra. Can be removed altogether by setting it to the same as the background colour.
cervical-height
The height of the boxes drawn to contain "cervical" vertebrae, i.e. those before the anchor point.
The value can be any string that is interpreted as identifying a length in SVG -- for example, 2em, 100px or 2.4cm. See http://www.w3.org/TR/SVG11/types.html#Length
2em
100px
2.4cm
cervical-width
The width of the boxes drawn to contain "cervical" vertebrae, i.e. those before the anchor point.
cervico-dorsal-color
If specified, this is the colour in which the vertical line through the cervical-dorsal anchor points of the aligned vertebral columns is drawn; otherwise, no line is drawn.
cervico-dorsal-offset
The offset of the cervico-dorsal anchor point across the area of the drawing. Should between 0 and width.
dorsal-height-gradient
If defined, the height of each successive dorsal vertebra exceeds that of its predecessor by the specified amount. Can be used to produce increasingly tall (or increasingly short if negative) dorsal vertebrae.
There is currently no corresponding cervical-height-gradient setting.
cervical-height-gradient
dorsal-height
The height of the boxes drawn to contain "dorsal" vertebrae, i.e. those after the anchor point.
dorsal-width
The width of the boxes drawn to contain "dorsal" vertebrae, i.e. those after the anchor point.
font-family
The font family to be used for captions, including taxa and specimen numbers. Taxon names are rendered in the italic variant of the font, specimen numbers in the regular font. To inhibit the use of italics for a taxon name (e.g. because it's a clade or family rather than a genus or species), precede it with a forward slash (/).
/
The font family may be specified by a list of family-names, as in SVG and CSS. See http://www.w3.org/TR/SVG11/types.html#DataTypeListOfFamilyNames
font-size
The font size to be used for captions.
height
The height of the entire picture to be generated.
state-X-color
The states of individual vertebra, represented by single characters and indicated by Data lines, are defined by state-X-color and state-X-polygon pairs of settings. state-X-color specifies what color to use for drawing vertebrae of the state corresponding with the characters X.
state-X-polygon
This specifies how vertebrae with state X are drawn within their boxes. It is specified as a space-separated sequence of x,y pairs, each representing a point within a notional 1.0-by-1.0 space; a polyline between each of these points in order and returning to the first point is drawn and filled in the colour specified by the corresponding state-X-color setting.
The x-coordinate runs from left to right; the y-coordinate runs from top to bottom.
Examples:
0,0 0,1 1,1 1,0 simply fills the box with solid color.
0,0 0,1 1,1 1,0
0,0 0.5,1 1,0 draws a triangle pointing downwards.
0,0 0.5,1 1,0
0.1,0.3 0.9,0.5 0.1,0.7 draws a small, narrow triangle pointing to the right.
0.1,0.3 0.9,0.5 0.1,0.7
taxon-height
The vertical spacing between consecutive taxa.
text-y-offset
0
The distance to move text (i.e. taxon-and-specimen captions) down the drawing relative to the vertebrae (or up if the offset is negative). This can be useful to tweak alignment depending on what font-family and size are used.
width
The width of the entire picture to be generated.
See examples/bifurcation/bifurcation.vcd and examples/pbj/pbj.vcd in the distributon. (Note that the latter must be preprocessed by the m4 macro processor.)
examples/bifurcation/bifurcation.vcd
examples/pbj/pbj.vcd
vcd2svg - program for translating VCD files into SVG.
Copyright (C) 2013-2014 by Mike Taylor <mike@miketaylor.org.uk>
GNU General Public Licence v3.0
To install SVG::VCD, copy and paste the appropriate command in to your terminal.
cpanm
cpanm SVG::VCD
CPAN shell
perl -MCPAN -e shell install SVG::VCD
For more information on module installation, please visit the detailed CPAN module installation guide.