Basic Concepts
Like many other specialised tools, protograf has its own set of terms and concepts that act as “short-cuts” to define its functions and behaviour. Some of these are likely to be common to other graphics editing or programming tools, but some are specific to it.
This is a general discussion; it may also be useful to look at the more detailed definitions of some of the terms in the section covering terminology.
How you’ll use protograf
You will be using protograf to write what is termed a script i.e. a recipe or list of instructions that are stored in a file.
A script’s instructions are used to define a game board, a set of cards or tiles, or any other, similar, regular graphical design of your choice.
You will then use Python to “run” the script. Python will take the file you have written, and step through it, line by line, from top to bottom, to finally create an output PDF file or, optionally, PNG or GIF images, that will show the outcome of this process - hopefully with your desired design!
If you want to make changes to the design, then you add to, delete, or change, the instructions in your script and use Python to process it again to create an updated version.
The “script” concept
Creating a script is similar to the process of building a house; in the sense that the instructions which come first create underlying parts that are “deeper down”; in the same way that a foundation is below a floor, which in turn is below the walls, which are below the ceiling, which is below the roof. The lower layers are often not “visible”, even if they are there, but they are just as important!
So, for example, a page may contain rectangles representing cards. Each card may then have additional rectangles placed on it, representing some aspect that is part of your card design. Those rectangles, in turn, could have text, images or icons on/inside them. So, each item that is created later can “obscure” some part - or even all - of item, or items, defined previously.
Its also possible to define things earlier in a script that are used, or reused, later on.
In summary - the order of instructions in a script is important as this will affect what you see at the end!
Hint
For more detail on what goes into a script, see the section on Script Anatomy.
The “position” concept
When using protograf what you are doing is defining where and how various things should appear on a page. A script can create multiple pages, but will always have at least one.
The position of something is where it will be drawn on the page. To do this, you provide values for both x - the horizontal position - and y - the vertical position - for each thing that you want to appear on the page.
If you look at upright A4 paper - which is 21cm wide and just less than 30cm high - then a point in the middle of the page will have an x position of 10.5cm - its distance from the left edge of the page; and a y position of 14.8cm - its distance from the top edge of the page. Similarly, for a US Letter-sized page of 8.5” by 11”, a point in the middle of the page would have an x position of 4.25” and a y position of 5.5”.
As the use of margins is common for most documents and drawings, nearly all distances in protograf are considered to be relative to the margin settings i.e. if the page margin, for the A4 page mentioned above, was set to 2.5cm (1”) then to locate a point at those same distances would mean using an x position of 8cm and a y position of 12.3cm, as the margin size will be automatically added onto the values you specify for the position.
The “command” concept
Instructions in protograf are termed commands.
Commands are usually written with an initial capital letter. They are effectively “imperative” in nature, causing something to happen right away; for example:
Save()- instructs the program to save the output to fileCircle()- instructs the program to draw a circle at this point in the script
The summary list of all commands is a useful reference for checking what is available.
Important
In some cases you will use the same command but with a lowercase initial — often when defining shapes (including images and text) for cards when constructing decks (see Working with Cards).
When used in this way, the command is not carried out straightaway, but deferred for activation later on in the script.
The “element” concept
Rather than use the slightly clumsy term “thing”, protograf uses the term element.
Almost everything in protograf that appears in the output is considered to be an element of some sort.
Elements are often geometric shapes, such lines, circles or rectangles, but can also be text or images.
Examples of some of the available geometric shapes include:
Circle
Ellipse
Hexagon
Polygon
Rectangle
Rhombus
Square
Stadium
Star
Triangle
Descriptions of all of these kinds of shapes, and how to create and use them, are provided in the section on core shapes.
Other elements include things like hexagonal grids, regular layouts and cards.
Element properties
Elements, including shapes, can have other settings apart from their position.
Common examples of settings include:
height — size in the vertical direction, of some shapes
width — size in the horizontal direction, of some shapes
stroke is the color, of the line used to draw a shape; sometimes called the “pen” in graphic applications
fill is the color used to “fill in” an area of a shape; sometimes called the “brush” in graphic applications
radius or diameter — to set the size of a circle or polygon
paper size, margins, and so forth for the document as a whole
All of these types of settings are termed properties.
Most of the common properties are defined in the section covering terminology and their usage is covered in the section on core chapes. Some shapes have more extensive properties.
Working with color
Everything we see has color.
Color in protograf, can be defined in the same way as it is in pages
that appear on the web i.e. in RGB — red-green-blue — hexadecimal
format; for example, #A0522D represents a darker shade of the color that we
would likely term “brown”, while “basic” colors have their own
values; “yellow” is #FFFF00, “red” is #FF0000, and
“blue” is #0000FF. RGB colors in protograf can also make use
of names from a pre-defined list - for example #A0522D is defined as the
color sienna.
Color can also be defined using CMYK color values; for example the sienna
color can also be set via these 4 values: "0, 48.75, 71.87, 37.2".
Color properties in protograf are typically set either with a “fill”, which defines the color of a whole area, or a “stroke” which determines the color of a line or of text.
The default colors in protograf are
white for areas and black for lines.
Hint
For more details on colors, and color models, refer to the section on Color-orientated Terms.
Working with units
All positions, heights, widths, distances, line thicknesses and other kinds of lengths or sizes all need to be measured in a particular set of units.
Units are important, and protograf requires that the same set of units applies throughout a specific script (see this cautionary story on why not to mix units!)
In the USA, people tend to use the so-called Imperial System. In
protograf this means that distances might be measured in units of
inches. Inches are often shown with a double-quotes symbol (")
in documents; in protograf inches are often referred to using the
abbreviation in.
In almost all of the rest of the world, the Metric System is in use. In protograf this means that distances will be measured in units of centimetres; referred to in protograf as cm. Alternatively, you can choose to use millimetres, abbreviated in protograf as mm.
The default units in protograf are cm.
Hint
For conversion purposes, 1 inch equals 2.54 centimetres or 25.4 millimetres.
protograf also allows units of points, which are the measurement units traditionally used in the printing industry. There are 72 points in 1 inch. Internal calculations in protograf are all done in point units i.e. all inputs, regardless of being inches, centimetres, millimetres — or anything else — are converted to points.
Note
In a few cases, protograf adopts the word “size” or “width” where point units are in use e.g. font size, stroke width and dot width, but because “size” is such a general term, it’s not really used elsewhere.
The “stroke” concept
While the majority of size-based element properties in protograf work with the “normal” units you have chosen — inches or centimetres — some use points (see working with units above). These include font size, that you’re likely familiar with from word processing programs, and line thickness — termed “stroke width”. The reason for doing this is to maintain consistency with other, existing tools.
The “default” concept
A “default”, in terms of protograf, is a value or setting for something — usually a property — which is used unless you specify otherwise.
Defaults are helpful for quickly drawing or testing something until you’re ready to make decisions about your own specific settings or values.
Some examples of defaults are:
the default margin for pages in the output PDF is
0.635cm or 1/4” (one quarter of one inch); the main reason for this choice is to ensure that a 3x3 grid of Poker-sized cards fits onto one page!the default paper size for pages in the output PDF is
A4— similar to the USLettersize i.e. A4 paper is 21 cm x 29.7 cm (8.268 inch x 11.693 inch) and Letter paper is 8.5 inch x 11 inch (21.59 cm x 27.94 cm)the default units are centimetres (cm)
the default x and y positions are each
1(one) — with default units that equates to 1 cmthe default line length is
1(one) — with default units that corresponds to 1 cmthe default line stroke width is
1point — that corresponds to 1/72 inches (or 0.353 mm)the default line stroke color is
black— a hexadecimal value of#000000the default area fill color is
white— a hexadecimal value of#FFFFFFthe default font is
Helvetica, with a size (height) of12points and a stroke color ofblack
Hint
A default which may be less obvious is the name of the output file created
by protograf. This matches the name of the script but the
extension is changed to .pdf because this is the default output type
that is created. So, if your script is called test01.py then the
default output file that is created will be called test01.pdf.
Use the Create command to set your own output filename.
Finally — and perhaps confusingly — protograf also allows you to create your own “defaults” which represent properties that you want to share among a number of geometric shapes, or text, that make up your design; for more on this, see the Default and the Common commands.