The Vrr Project Documentation

0. Note

The Vrr project is being developed and many features, even the most important ones, are not yet fully implemented (for various reasons). In the following text, such features are marked with a "NYI" (not yet implemented).

1. Introduction

Vrr is a programmable geometrical Vector gRaphics editoR. Its main features are:

See the kernel overview to learn about the data structures, types of geometrical objects etc.

2. guile-vrr

The program has two main running modes: one has a GUI and the other one does not. The latter is called guile-vrr and is a Scheme command line expecting Scheme commands, by which you can access all the program functionality except for the GUI. You cannot view images; but you can create, load, edit, save them and so on.

These are some documented Scheme functions accessible from the console.

To learn about the Scheme programming language, see this Scheme Tutorial. To learn even more, see the Structure and Interpretation of Computer Programs book or the Revised Report on the Algorithmic Language Scheme.

3. The GUI

3.1. The windows

3.1.1. The Main Window

At the beginning opens the main window. It allows you to do some basic actions not connected to any particular document, create new documents or load documents from files. It can be hidden and open again without quitting the whole program (provided that you have some view windows open).

3.1.2. The View

The View The purpose of the view window is to display the contents of a document's page. Each view displays one page, while a page can be displayed in more independent views. All changes performed to the page are displayed in all views at once. All views displaying the same page can be used interchangebly. By closing the view, you do not delete the page nor the document containing the page; you only close the view. After adding a document containing some pages to the universe (by opening it or by creating new), a view for the first page is opened.

The buttons in the toolbar can be used to create new graphic objects, switch between factory states and set snap modes (see 3.3 Go Factory). On toolbars, there are some groups of buttons, set apart by button with horizontal separator line in it. Clicking on this separator button rolls up / down all buttons coming under this group. In the statusbar of the view, you can see hints about what to do in the particular factory state, and the current zoom and rotation settings of the view.

PencilThere is also a pencil icon in the statusbar. It disappears and appears again from time to time and marks the views of the current context page (see Context). All context actions (like keyboard shortcuts or so) are related to the current context.

The main part of the view is a drawing area where the geometrical objects contained in the page are drawn. The area is clickable and mouse actions have the following meaning:

Use scrollbars to move in the drawing area. By clicking on the scrollbar arrows, you can move even farther than the current editable area borders and thus have the area enlarged.

View Navigator In the corners between scrollbars and rulers, there are four buttons. Upper buttons rotate whole view according to the arrow's direction. The lower right button shows the View Navigator window containing the preview of whole page. The green rectangle in the preview represents the currently visible region of the page in the view. You can move it and change the visible region of the view accordingly. Enter new values of zoom and rotation to adjust preview. Button reset sets zoom to 100.0% and rotation to 0 degrees.

3.1.3. The Universe Browser

Universe Browser The universe browser shows you the tree structure of the whole universe. Here the left mouse button performs selection in the Gimp-like style: Shift + click adds to selection, Ctrl + Click removes from selection, while a single click clears the current selection and selects the clicked object.

The selected objects are marked with a color. As the program has two different selections -- selection of "namespace objects" (documents and pages) and selection of GOs -- each of them is showed using a different color. The selections are orthogonal, hence changed independently.

The right mouse button opens a context menu. The menu items are supposed to be executed on the current selection and may be disabled accordingly. If there is no selection some other objects are considered current (see 3.2.).

3.1.4. The Undo History Window

Undo History The undo history window can be open for a page or for the universe. It shows the list of all actions (which are, in fact, transactions) that have been done or undone on the particular page or on the universe. The undone actions are striked through. The middle button in the toolbar allows you to jump to the selected undo item.

3.1.5. Property Window

Property window The property window allows changing object's properties. Each object, according to its type (segment, circle etc.), contains some specific properties, which can be - in general - changed.

Properties with dimensions are associated with a dimension unit. By setting the unit, you modify the display value of the property, not the property itself. You can also create and use your own units (click on "New ..." in unit combo box). When creating a new unit, you enter the multiplier against the base unit.

For some properties, there is a more specialized editor, like the color editor, text editor, filename editor etc. In that case, there is a button in the property window that opens the editor.

You can also add your own properties (the "Add" button) or delete properties you've created (the "Delete" button).

3.1.6. Text Editor

Text Editor When creating a new text (or TeX text), you first specify a hanger -- location of the text reference point. Then the Text editor opens. The Text and TeX text editors differ slightly, but basically they are the same.

In case of the ordinary text, there are additional widgets for choosing the font and font size. The font list contains 10 last used fonts (if no fonts were used so far, it's 10 first found fonts). If you want to load all possible fonts, click on the button Load all fonts and the list in combo box will be filled with all installed fonts found (this may take a while). The font size is in points.

You can specify the position of the chosen reference point relatively to the text bounding box. For example, if you set the refpoint values to 0.5 and 0.5, the text will be positioned in such a way that center point of its bounding box equals the reference point.

Write the text to be displayed into the text area or load it from a file in the UTF8 character coding. You can't display empty text string.

Any changes you have made take effect after pressing the "Refresh" button or by pressing the Ctrl + Return keyboard shortcut.

3.2. The Context

During your work in the program, some objects or windows become implicitly significant from time to time: the object you clicked last, the toplevel window or the current selection. So, when performing an action, you do not have to specify all the subjects explicitly. The collection of these significant things is called The Context. It consists of:

The selection has always the highest priority. If the selection is empty, the other objects are used. Almost all actions like keyboard shortcut commands, menu commands etc. operate with the current context. For example, if you press "Ctrl+Z", which means Undo, the last action is undone in the context page.

PencilThe views displaying the current context page are marked with a pencil icon. Note that all views displaying the same page can be used interchangeably, so more than one view can be marked by this icon at the same time.

3.3. The GO Factory

The GO factory is a mechanism for creating GOs. It works similarly to a regular automaton: you set the starting state (e.g. "Create a segment") and then choose the desired arguments of the operation (in this case, two hangers), step by step. By pressing the BackSpace key, you return one step back; by pressing Esc, you cancel the creating process and delete the GO that is being created.

The GO factory is global for the whole universe. It can operate on at most one page at the same time. Setting some other page as the context page resets the process. Any action incompatible with the GO factory (which are almost all operations) breaks the process as well. Also, if you switch the GO factory to a start state during creating a GO, the process is cancelled.

The interface for working with the GO factory is contained in the view. You can toolbar buttons switch between factory states, by clicking the drawing area you position the points as arguments of the current operation, select objects, move the transformation gadgets and thus transform them, etc. The argument required in the current state is described in the status bar.

Once you choose (usually by clicking an object with the left mouse button) the desired argument, it may succeed or fail. In case of success the factory moves to another state and allows you to choose another argument. In case of a failure (e.g. when creating a circumscribed circle of three points and having chosen the first two points as equal) the factory reports an error and asks you to choose the last argument again. The error can occur for various reasons: when trying to create a circle circumscribed to three collinear points, or move a fully dependent object, for example.

When the process is finished, the factory returns to the starting state again so that you can create another GO of the same type.

The GO factory has the following kinds of states/modes: select + transform mode, other transform mode, anchor rehanging mode and go creating modes. We shall describe these modes in more detail.

3.3.1 Select and Transform Mode

Select mode When in the select and transform mode, the selection works similarly as in the Universe Browser. By clicking a go, you select it; by Shift+clicking you add it to selection and by Ctrl+clicking, you remove it from selection.

Moreover, you can use rectangular selection: by clicking and dragging the mouse cursor make a green rectangle to specify some graphic objects. Thus, all objects enclosed by the rectangle are selected/added to selection/removed from selection.

The bounding box of the selected objects is framed with a red line containing transformation gadgets. By dragging these, you transform the selected objects with affine transformations. Their functions are:

For scale and rotate transformations, the red centerpoint is the fixpoint. The gray centerpoint shows the current center of the bounding box (which may differ from the red one).

When holding the Shift key, different gadgets appear. There is a blue segment running out of the centerpoint - the axis. For skew operations, it represents the fixed points. The functions are:

In case that the bounding box of selected objects is (almost) not two-dimensional, only some gadgets are shown and only some transformations are applicable. These are move, scale and rotate for horizontal and vertical lines and move for points.

3.3.2 Santiago's Transform Mode

TransformTBA

3.3.3 Anchor Rehang Mode

Rehang This mode allows you to rehang anchors, which you might imagine as slots for something specified during creation of the go. For example, if you created a segment, you hung two anchors on the selected points (hangers), the startpoint anchor and the endpoint anchor. (See kernel documentation for more information). Now you might want to change the position of the anchors -- rehang one to a different hanger.

First, choose a go by selecting it. Then choose one of its anchors by clicking it. Then move the mouse cursor, you can see the anchor moving and causing the anchor's GO to be recomputed. Then click a hanger, the anchor gets hung on it.

Anchors are displayed as green triangles, whereas hangers are blue triangles.

3.3.4 GO Creating Modes

Creating Almost all factory icons represent states for craeting new GOs. To create a GO, press such an icon. Each GO is determined by some things: points (hangers) and numbers, maybe more. You will be asked to specify all information needed -- follow the instructions in the statusbar of the view. Positional information is specified by clicking the drawing area, numeric data can be edited in the property window. The following example tries to clarify this:

3.3.4.1 An example of creating a new go

1 2 3 First, press a button according to what GO you want to create. In the first picture, you can see the button "Create a new quadratic Bezier" pressed. Then position the mouse cursor to the desired starting point and click the left mouse button.

Now the Bezier curve is created, but you need to specify two more points: the control point and the endpoint. Do this by moving the mouse and clicking the left button. You can see the curve changing to respect to point positions you have specified.

After specifying the third point, the curve is created and you can start creating another or do something else. (Note that the curve created became the context object now and you can edit its properties in the context property window.)

3.3.5. Snap

Hangers Grid Lines Intersections When choosing the arguments, you usually choose points (more precisely, hangers). If no snap mode is set, the chosen point always becomes exactly the position where you clicked. If you turn some snap modes on, the chosen point may be aligned to something near the position you clicked. The possible snap modes are:

The snap modes are independent and can be switched on and off and combined arbitrarily. If several modes are on, the nearest matching point is chosen (but not farther than a certain tolerance in pixels).

4. Geomlib

All geometrical computations are performed by our library called geomlib independent on other parts of the program. Inside the library, we use for example the Jenkins-Traub algorithm for finding roots of a polynomial of degree n, operations with rational Bezier curves and Bezier curve sets: finding intersections, the nearest point on a curve to the given point, calculating the length of a rational Bezier curve, linear affine transformations, ... We have also implemented a planar search structure R*-tree.

5. The Drawing mechanism

The drawing mechanism draws all existing objects, but so far in a very simple way (black lines one pixel thick). It redraws the objects automatically after a change in the kernel. In supports zoom and affine transformations of the objects (settings of the view without changing the kernel structures).