Dickimaw Books Blog

FlowframTk Descriptions and Tags 🔗

Below is an image of a house that I created in FlowframTk. It consists of a rectangle with a black outline and yellow fill colour (the wall), a triangle with a black outline and a red fill colour (the roof), a black filled rectangle (the door), and four smaller rectangles each with a black outline and a white fill colour (the windows). These objects are all paths defined by control points. In this simple example, all paths are made up of line segments.

The screenshot includes the mouse cursor, which is in its default pointing arrow state. The cursor shape varies depending on the currently selected tool. The grid unit has been set to "cm" but the storage unit has been set to "mm". This means that if the image is exported to PGF code, the coordinates will be in millimetres. (The grid unit and storage unit are independent, but it’s best to choose compatible units. You would likely get rounding errors otherwise.)

Sometimes I have complicated images with a large number of small or overlapping paths and it can become difficult to select a path that needs to be edited, so I added a dialog that lists all objects that make up the image. I can then find the object I want from the list and select it that way.

The screenshot below shows the find dialog for the house image.

I haven’t assigned a description to any of the image objects, so a generic description is used for each one:

Path: 4; line rgba(00 00 00 FF) fill rgba(FF FF 00 FF)
Path: 3; line rgba(00 00 00 FF) fill rgba(FF 00 00 FF)
Path: 4; line rgba(00 00 00 FF) fill rgba(FF FF FF FF)
Path: 4; line rgba(00 00 00 FF) fill rgba(FF FF FF FF)
Path: 4; line rgba(00 00 00 FF) fill rgba(FF FF FF FF)
Path: 4; line rgba(00 00 00 FF) fill rgba(FF FF FF FF)
Path: 4; line rgba(00 00 00 FF) fill rgba(00 00 00 FF)

So each object can be assigned a description to make it easier to find in this list. In the screenshot below, I’ve selected the bottom right window and set the description to “bottom right”.

I likewise added a description to all the other objects.

A description can only be set if a single object is selected, but it’s possible to assign a tag to multiple objects at the same time. Unlike the description, a tag is restricted to alphanumerics and a limited set of punctuation. If you want to assign multiple tags, you can use a space-separated list.

In the screenshot below, I have selected all four windows and set the tag for all of them to “window”.

Now let’s go back to the find dialog:

The list now shows each object’s description: wall, roof, top left, bottom left, top right, bottom right, and door. It’s now much easier to see which item corresponds to which object, but for an image with many objects it can still be a lengthy list to scroll through.

The filter setting can be used to shorten the list. In the screenshot below, I applied a filter to only show objects that have the tag set to “window”. The list now just contains the items for the four windows.

It’s also possible to assign a description to the entire image. In the screenshot below, I set the image description to “A House”.

The image description isn’t used by the find dialog, but it is used by some of the export functions.

I exported the image to a file called house.tex which contains the PGF code to draw the image. Omitting the actual drawing code, the file contents are:

% Created by FlowframTk version 0.9.1
\iffalse
% This image may require the following commands in the preamble:
\usepackage{flowframtkutils}
% The normal size font is assumed to be 10pt
% End of preamble information
\fi
\begin{pgfpicture}
% A House
 PGF code to set the bounding box 
% wall
 PGF path drawing code
% roof
 PGF path drawing code
% top left
 PGF path drawing code
% bottom left
 PGF path drawing code
% top right
 PGF path drawing code
% bottom right
 PGF path drawing code
% door
 PGF path drawing code
\end{pgfpicture}

Although I designed FlowframTk so that it shouldn’t be necessary to edit the exported file, if the exported image doesn’t turn out as expected, I need to look through the file to find out where the export went wrong, and it’s useful to have each object starting with its description as a comment.

The block at the start of the file indicates what you may need in your document preamble. The font information isn’t applicable as the example image doesn’t contain any text.

This example is simple enough just to include the pgf package without needing to load flowframtkutils (supplied with flowfram). So my document source code can simply be:

\documentclass{article}

\usepackage{pgf}

\begin{document}

\begin{figure}
\centering
\input{house}
\caption{An Example Image}
\end{figure}

\end{document}

More complicated images may required flowframtkutils (which automatically loads pgf). The flowframtkutils package also provides \includeteximage which may be used instead of \input. This has the advantage of using the same search path as \includegraphics (set with \graphicspath) and it has an optional argument that includes a subset of the graphicx options to apply transformations. Here’s a modified version of my document that scales the image:

\documentclass{article}

\usepackage{flowframtkutils}

\begin{document}

\begin{figure}
\centering
\includeteximage[scale=0.5]{house}
\caption{An Example Image}
\end{figure}

\end{document}

It may be that you actually want to make use of the description or tags in the document. The export dialog provides a setting that will insert code to markup each object in the exported file, but that will be the topic of another post.