Terminology

protograf uses many terms; most of which should — hopefully! — be fairly obvious by their name, or by the context in which they are used.

However, in order to help with clarity, below is a reasonably comprehensive list of terms used in different places, grouped by what aspects they affect.

Note that some shapes, such as the Hexagon, Circle, Line, or Rectangle, have extensive customisation properties available; its better to refer to their specific descriptions to understand exactly how these can used.

This section is meant to be complementary to the concepts, terms and ideas for protograf discussed in Basic Concepts.

protograf Jargon

↑

protograf uses a number of ‘generic’ terms which you’ll see in many places in the documentation:

  • command - an instruction that is specified in a protograf script; see a full list in the Commands section

  • default - a value set by protograf if no other is given; for example, the line length defaults to being 1 centimetre long

  • list - a number of comma-separated values enclosed in square brackets e.g. [1, 2, 3] — whihc are usually assigned to a property

  • property - an aspect of a command or shape that helps define how it works or looks; for example, a circle might have its size defined by using a radius property of 2 centimetres - in a script this would be shown as radius=2

  • shape - a geometric element, for example, a circle, square, text or line i.e. something that can be drawn — see a list in the Shapes section

  • script - a file, that can be run, containing various protograf commands — see an outline in Script Anatomy

  • set - a number of comma-separated values enclosed in round brackets e.g. (1, "a") — these are usually assigned to a property

  • run - to cause Python to act on the script so that all instructions in it are carried out — this should usually cause an output file to be created (or recreated)

  • vertex / vertices - the sharp “points” at the intersection of the lines used to construct a shape; for example, a triangle has 3 verticesl; a square has 4 vertices and a hexagon has 6 vertices.

  • _x and _y - some terms can be modified to be specific for x (left to right) or y (top to bottom) distances by appending one of these underscore-prefixed terms to them

Color-orientated Terms

↑

RGB Colors

An RGB color is defined in the same way as it is in pages that appear on the web i.e. in red-green-blue hexadecimal format, for example, #A0522D represents a shade of the color that we would likely term “brown”.

RGB colors can also be chosen from a pre-defined list of names, for example #A0522D is pre-defined in protograf as the color sienna.

A PDF file colorset.pdf shows all the names and RGB colors that are available.

Hint

For more details on hexadecimal colors, refer to http://www.w3.org/TR/css3-color; the color names are listed in the section https://www.w3.org/TR/css-color-3/#svg-color (this list can also be found at https://en.wikipedia.org/wiki/X11_color_names)

CMYK Colors

A CMYK (cyan-magenta-yellow-black) color can be set using 4 numbers for these four colors.

To set these as percentage values - between 0 and 100 - use a string value, for example, "0, 48.75, 71.87, 37.2" (which corresponds to the color sienna color described in the previous section).

To set these as fractional values, use a set of numbers enclosed in (...) brackets, for example: (0, 0.4875, 0.7187, 0.3725)

Important

If you need all colors in the output PDF document to be in this format, then ensure you set the property color_model="CMYK" in the Create command.

Quick Colors

A list of “one-letter” colors is also available (based off of a popular Python library called matplotlib); their RGB hexadecimal codes are also shown here for reference:

  • b is blue (“#0000FF”)

  • c is cyan (“#00FFFF”)

  • d is dark blue (“#293BC7”)

  • e is earth/natural (“#F3B54A”)

  • f is forest green (“#007700”)

  • g is green/malachite (“#32CD32”)

  • h is brown/cinnamon (“#D2691E”)

  • i is pink (“#E6506E”)

  • k is black (“#000000”)

  • l is picton blue (“#00BFFF”)

  • m is magenta/violet (“#BF00BF”)

  • n is orange (“#FFA500”)

  • o is white (“#FFFFFF”)

  • p is purple/lavender (“#EE82EE”)

  • r is red (“#FF0000”)

  • s is silver/gray (“#C0C0C0”)

  • u is dark/derby brown (“#4C271B”)

  • w is white (“#FFFFFF”)

  • y is yellow (“#FFFF00”)

  • x is black (“#000000”)

Setting Colors

In general, color can be set for the lines (stroke) and areas (fill) that are being drawn on a page by assigning values to the respective proprerties of a shape that is being drawn.

  • dot_fill - the color in which a circle is to be drawn at the centre of a shape

  • fill - the color with which an area is filled

  • outline - sets the line color, and at the same time sets the fill to be None

  • stroke - the color in which a line or text is drawn; there are many strokes for particular types of lines that are set by prefixing this term with the name of the item in question; for example: cross_stroke; grid_stroke; label_stroke; petals_stroke, perbii_stroke; radii_stroke; etc.

  • stroke_fill - sets both the line (“stroke”) and area (“fill”) to be the same color

Important

Note that it is possible to use the term None in place of a specific color; this effectively means that nothing will be drawn there - this results in an “invisible” line or area!

Position- and Location-orientated Terms

↑

Everything in protograf that needs to be displayed or drawn or positioned must be placed at a position on the page; i.e. each thing must have both a horizontal position - its x value - and a vertical position - its y value. These respectively represent the distances from the left- and top-edge of a page or a card.

Location is a more general term; it can be a combination of the x and y positions; it could be a row and/or column identifier; it could be a sequence identifier; or just a indicator of where something is relative to something else, for example, a coordinate being drawn at the top of a Hexagon.

  • align - used to move Text horizontally, relative to its starting location; can be one of: justify, left, right, or centre

  • align_horizontal - used to move an Image horizontally, relative to its starting location; can be one of: left, centre, or right

  • align_vertical - used to move an Image vertically, relative to its starting location; can be one of: top, middle, or bottom

  • cx - the centre position of a shape, measured in the horizontal direction; its usually the case that the distance is not absolute, but relative to some other value e.g. distance from a margin; or the edge of a Card

  • cy - the centre position of a shape, measured in the vertical direction; its usually the case that the distance is not absolute, but relative to some other value e.g. distance from a margin; or the edge of a Card

  • cxy - the centre position of a shape, specified as a Point

  • elevation - a relative vertical location within a shape; can be one of: top, middle, or bottom

  • x - the position of a point in the horizontal direction; its usually the case that the distance is not absolute, but relative to some other value e.g. distance from a margin; or the edge of a Card; or the away from the centre of a Hexagon in a grid

  • y - the position of a point in the vertical direction; its usually the case that the distance is not absolute, but relative to some other value e.g. distance from a margin; or the top edge of a Card

  • xy - the top-left position of a shape, specified as a Point

Size- and Length-orientated Terms

↑

The majority of length properties — width, height, diameter etc. — will be numeric values, corresponding to the unit in use unless otherwise noted. The default is usually 1. The default unit is centimetres (“cm”), so the default length is 1 centimetre.

Some sizes are set in points — there are 72 points in an inch — so as to align with existing conventions, or simply because these items are typically very tiny. As far as possible, the term size is reserved for these settings; for example, font_size and dot. An exception is stroke_width which is also in points, again because of convention.

A few sizes are given descriptive names; this makes them a little easier to set.

  • auto_frame - allows the height of an Image on the page to be calculated if the width is set, or vice-versa

  • caltrops - a descriptive term for the relative dimensions of a “caltrop” - the small three-pointed shape drawn at the vertex of a hexagon

  • cross - the height and width of the intersecting lines drawn at the centre of a shape

  • dot - the diameter of a small Dot in points

  • height - the vertical dimension of a shape e.g. a Rectangle or a bitmap Image

  • leading - the spacing, in points, between lines of wrapped Text

  • interval - the distance between the centres of a series of shapes; typically in a repeated pattern of some type

  • margin - used in Create command to set all margins for a page; the default for any margin is 0.635cm or 6.35mm (quarter of an inch)

  • margin_top - used in Create command to set a top margin for a page — this overrides the margin property, if any

  • margin_bottom - used in Create command to set a bottom margin for a page — this overrides the margin property, if any

  • margin_left - used in Create command to set a left margin for a page — this overrides the margin property, if any

  • margin_right - used in Create command to set a right margin for a page — this overrides the margin property, if any

  • paper - used in Create command to set the paper format in the document; either ISO series — A0 down to A8; or B6 down to B0 — or a USA type; the default is A4. NOTE: to switch to landscape orientation, append an l to the name; so "A5-1" set the page to use A5 landscape paper

  • radius - the radius of a Circle

  • scaling - the amount by which a Polyline, drawn with a snail, should be expanded or shrunk; e.g. 0.5 makes it half-size and 2.0 doubles its size; note that images do not have scaling as such — simply set the height and width of the Image and the image will be auto-sized to fit (SVG images use a vector-format, so there will be no loss of resolution through rescaling)

  • side - the length of a side of some shapes (e.g. Square, Polygon, Grid) as well as the distance between each adjacent point in a TriangularLayout

  • snail - a means to draw a Polyline or Polyshape by setting a series of values to represent relative increments of distance, or changes in angle, of the line used to do the drawing

  • stroke_width - the thickness of a line in points; many specific widths are set by prefixing this term with the name of the item in question; examples include: cross_stroke_width; grid_stroke_width; radii_stroke_width; perbsis_stroke_width, etc.

  • width - the horizontal dimension of a shape e.g. a Rectangle or a bitmap Image

Amount- and Count-orientated Terms

↑

  • sides - the number of sides of a Polygon shape

Hint

The concept of counting is also important when creating a Track or a Sequence or a deck of Card s — each item being created is assigned a sequence number which can be used for reference or labels or text.

Direction-orientated Terms

In general, there are two primary ways of determining direction of something; either by a compass direction or by an angle. Other, more descriptive directions are also used.

The angle is the amount of rotation, in degrees, starting from a value of zero (0) which is assumed to be the line parallel to the bottom of the page as you would normally look at it. Ninety (90) degrees is the angle of a line parallel to the vertical sides of the page, and so on.

The maximum allowed rotation is 360 degrees i.e. a full sweep around a circle.

A compass direction is one of the following:

Primary compass directions — with full names shown in brackets:

  • n (north) - normally corresponds to an angle of 90 degrees

  • s (south) - normally corresponds to an angle of 270 degrees

  • e (east) - normally corresponds to an angle of 0 degrees

  • w (west) - normally corresponds to an angle of 180 degrees

Secondary compass directions — with full names shown in brackets:

  • ne (north-east) - normally corresponds to an angle of 45 degrees

  • nw (north-west) - normally corresponds to an angle of 135 degrees

  • sw (south-west) - normally corresponds to an angle of 225 degrees

  • se (south-east) - normally corresponds to an angle of 315 degrees

Tertiary compass directions are also used for some geometry properties.

Note

If a compass direction is used in the context of a Hexagon, then the angle is “reinterpreted” to approximate its context e.g. the NE angle for a “pointy” hexagon is 60, not 45, degrees.

Properties that use directional terms include:

  • angle - the interior angle between first and second sides of a Triangle

  • clockwise - a True or False setting used to determine direction of travel around a circle

  • links - for a Line, which reference a vertex or perbis point, are used to join one or more shapes with a line

  • direction - can be any primary compass direction; used to show the travel route when moving through various types of layouts e.g. RectangularLayout

  • edges - can be any primary compass direction; used to indicate the sides of a Square or Rectangle

  • flat - the orientation of a Hexagon, meaning the top of it will be parallel to the bottom edge of the paper

  • facing - can be any primary compass direction; used to show orientation of some types of layouts e.g. DiamondLayout

  • flip - the relative vertical direction in which a rhombus must be drawn; can be either: north or south

  • orientation - used for drawing hexagons; can be either: flat or pointy

  • pivot - the angle by which a Triangle is rotated around its start point

  • pointy - the orientation of a Hexagon, meaning the top of it will make a “peak” relative to the bottom edge of the paper, and the flat edge will be parallel to the left side of the paper.

  • radii_shapes - a shape is drawn on the line of the compass direction of a shape’s radius

  • start - can be any secondary compass direction; for example, it is used to show in which corner of a RectangularLayout that shapes should first placed when creating a track

Styling-orientated Terms

↑

  • curve - sets the amount of “bend” for a line; cannot be used when some other styles such as a wave are used

  • dotted - allows a line to be broken into a series of “dots” — very short lines — of length equal to the width of the line being drawn, with spacing in-between each dot of that same length; to make a line dotted, simply use dotted=True

  • dashed - allows a line to be broken into a series of short lines, separated by spaces defined in a list; the first number is the length of the dash; the second is the length of the space between two dashes — note that sizes will be rounded to the nearest whole point value; so 2cm, which is equivalent to 56.693 points, will be changed to 57 points

  • _ends - this is part of a line property e.g. stroke_ends that changes the style of the line ends; it can be rounded which causes the ends of a line to be extended with a semi-circle; or squared which causes the ends of a line to be extended with an extra half-square. (In graphics terms, this can also be termed an end cap.)

  • transform - will change text in a Text command to uppercase, lowercase, or capitalise it

  • transparency - a percentage value from 1 to 100 that determines how “see through” a shape, or line, or area is; where 1 means it is not at all transparent and 100 means it is completely transparent. It is also possible to use a fractional number e.g. 0.5 equates to 50%. Some programs use the term opacity; but note that this is the inverse of transparency.

  • wave_style - this can be ‘sawtooth’ or ‘wave’ and causes the line to be drawn in that pattern, rather than as a straight line; the height of the wave is set by the wave_height

Display-orientated Terms

↑

  • corners - if assigned a number will cause short lines of that length to be drawn from each corner of a Rectangle — these lines can be further styled e.g. to show as small, triangular photograph holders

  • grid - a series of lines that are drawn in a pattern; protograf uses this term in many contexts — grids that cover the whole page; grids used for drawing game boards; and even small grid marks that are used for trmming, cutting or cropping cards

  • hatches - when used in combination with hatches_count will draw a series of parallel lines between two opposing sides of a regular shape in the specified direction(s)

  • hidden - a list of locations, indicated by their row and column identifier, which should not be used for display - the rest are displayed as normal

  • masked - a list of locations, indicated by their sequence number — i.e. their position in the drawing order — which should not be used for display — the rest are displayed as normal

  • radii - if given a value of True will cause the radii of a Polygon``or ``Hexagon to be shown

  • paths - a list of one or more pairs of compass directions, representing two edges of a hexagon shap,e between which a line — straight or an arc — is drawns

  • perbii - if given one or more numbers will cause the perpendicular bisectors (“perbii” is plural for the shortcut “perbis”) — lines from centre to the middle of the edges — of a Polygon, Hexagon or Rectangle to be drawn; a Polygon's unnamed edges are numbered from the east-facing one in an anti-clockwise direction

  • shown - a list of locations, indicated by their row and column identifier which are the only ones that must be used for display - the rest are ignored

  • stripes - will draw a series of parallel areas between two opposing locations of a Rectangle in any/all of the specified direction(s)

  • vertex_shapes - will cause a list of shapes to be drawn at the vertices of the parent shape

  • visible - a list of locations, indicated by their sequence number — i.e. their position in the drawing order — that must be used for display - the rest are ignored

Area-orientated Terms

↑

  • frame - used to demarcate the boundary of a Card; one of rectangle, hexagon, or circle

  • perimeter - used to demarcate the boundary of a StarField; one of circle, rectangle or polygon

  • peaks - a series of sets, each containing a primary compass direction and a value, that designate that the edge of a rectangle should be drawn as a triangular “peak”; e.g. a set of ('n', 2) would draw a 2cm high triangle on the upper (north) edge

  • shades - a way to fill in the rhombus-shaped subsections of a hexagon in order to create the effect of a Cube

  • slices - a way to fill in triangular sections of a square, rectangle or rhombus by supplying a list of colors; for a square or rectangle, a slices_line can also be used to create both trapezoids and triangles which gives the appearance of a building’s roof when viewed from above

  • tetris - when set to True will cause a Tetronimo to be styled as per the original Tetris game pieces

Miscellaneous Terms

↑

  • debug - a value can be set for this that will cause underlying values or locations or positions to be displayed e.g. using debug="n" for a layout will show small dots where each point in that layout exists

  • GIF - Graphics Interchange Format. A file format in which an image can be stored; its useful because it supports multiple layers and can be animated.

  • PDF - Portable Document Format. A widely used format to create documents such that they display the same way on all devices; its Useful because it supports the vector-format of protograf shapes.

  • PNG - Portable Network Graphic. A file format in which an image can be stored; its useful because it supports transparent backgrounds.

  • SVG - Scaleable Vector Graphics. A file format in which an image can be stored; its a vector-format unlike the bitmap- or raster-format of PNG and JPEG files, so its size can be changed without loss of quality.