﻿World Builder

DPRSim is the Dynamic Physical Rendering Simulator. See the README for more
info on the simulator in general.
The World Builder is a tool used to create .world files to be used in DPRSim
simulations. It allows the user to create or edit configurations of catoms 
embedded in one of several 3D lattices and to save these configurations in
.world format.


*******************************************************************************
Starting Builder

> ./dprsimgr -b [-w <world file>]

If the -w option is not used, the builder opens on an empty world 
(BUILDMODE.world). If -w is used, the specified world file is opened for 
editing; the resulting world can be "saved-as" a new world file or saved over 
the old one. When the -b flag is used, DPRSim opens the BUILDMODE.exp 
experiment file. Any experiment settings needed by a user of the world builder 
(catom radius, catom type, etc.) can therefore be viewed and edited in 
BUILDMODE.exp. These settings will not be saved in the created world, however.
They must always be specified in the experiment file when the experiment is
run.

*******************************************************************************
Using Builder

Overview:
---------

In builder mode, catoms are created in alignment with a 3D lattice selected by
the user. there are several ways to create (and delete) catoms:
- one at a time
- in groups (stamps):
  patterns copied from other .world files
  models generated from 3D model files (as solids or as shells of any thickness)
  prisms of user-specified dimensions (again as solids or as shells)

Catoms and groups can be created at arbitrary points in space, on or off the XY 
plane, and can be colored by the user as they are created. 

Other tools:
- GUID management: 
  view/change individual catom GUIDs
  set the GUIDs of all n catoms to the integers 1 through n
- Clear All
- Save As 

The Builder Window:
-------------------
After starting builder, the DPRSim builder window will appear. I find it
easiest to use the builder with the window maximized. Although builder mode
uses much of the simulator's graphics code, there are some visual differences.
First, a black pyramid marks the origin (0,0,0) in the viewport on the left.
This is useful for navigation and when creating world stamps (see below).
Second, the set of widgets on the right is different from those displayed by
the simulator normally. These controls and their use are described in 
"Builder Widgets". It is also worth noting that the "Start/Pause" button and 
"Simulation Progress" bar appear in builder mode. These controls are not used
by the builder.

Controls:
---------
Note: many commands function as they do in regular simulation mode, even if 
not mentioned here.

Arrow keys- move the camera forward or backward or strafe from side to side.

Mouse- moving the mouse lets the user position the "catom cursor", a semi-
transparent sphere. The catom cursor is used to select, create, and delete
catoms and groups of catoms. Normally, the catom cursor will appear on the
XY plane; pointing it at other catoms (depending on what mode the user is in)
will often cause it to "snap" onto the catom in question or onto a location
neighboring the catom. This is useful for building structures not confined
to the XY plane. The color of the cursor reflects the user's mode; green is
insertion mode, red deletion mode, and blue selection mode. When in stamp
mode, a semi-transparent group of spheres representing the stamp shape
replaces the cursor. In navigate mode, no cursor appears. For best
performance, use navigate mode unless another mode is actually necessary
(e.g. for creation or deletion of catoms).
For more on user modes, see "Modes" below.

Right click and drag- changes the camera angle.

Mouse wheel- Depending on whether the user has selected "Camera Z" or "Cursor
Z", scrolling the mouse wheel changes either the height of the camera or the
height of the catom cursor. See "Builder Widgets". When the catom cursor is
above the XY plane, a small sphere appears on the XY plane below it. This
shadow can be useful for keeping track of the location of the catom cursor in
3D space.

Left click- varies by mode. See "Modes".

Modes:
------
There are four main modes in which the user can operate: navigate, insert,
erase, and select. These are available in the "Catom Cursor" toolbar. There
is also one additional mode, stamp mode, which can be toggled separately from
the others.

Navigate: 
This mode should be used as a default. It is best for performance and should 
always be used unless another mode is actually necessary.
Cursor- none
Left click- no action

Insert:
Allows the user to insert catoms (or groups of catoms-- see "Stamp") at the
catom cursor's location.
Cursor- green
Left click- create catom(s) at the catom cursor's location

Delete:
Allows the user to delete catom (or groups of catoms) at the catom cursor's
location.
Cursor- red
Left click- delete catom(s) at the catom cursor's location

Select:
Allows the user to select a catom and display its GUID. The GUID can then be
edited (see "Builder Widgets")
Cursor- blue
Left click- display GUID of catom at cursor's location

Stamp mode:
This mode can be used simultaneously with the insert and delete modes. In 
this mode, instead of creating/deleting single catoms, the user can create or
delete a group of catoms. This group is either loaded from a .world file 
(using the "Stamp File" widget) or is generated from a 3D model or from user-
specified dimensions ("Create from Model" and "Create Catom Prism",
respectively). The catom locations are translated so that the group's origin 
is at the catom cursor, and the cursor takes on the shape of the group.
Cursor- color varies, shape is identical to that of the group to be manipulated
Left click- create/delete catom group as previewed by cursor

Builder Widgets:
----------------
To the right of the viewport is a vertical bar of widgets. These widgets are
used to set the user mode, to change global settings, to manipulate catom GUIDs,
and to generate catom groups from 3D models or prism dimensions.
Listed from top to bottom:

Lattice Type:
The default lattice type is cubic. Selecting a different lattice type causes 
all catoms placed by the builder AFTER the selection to be centered on points
in the lattice; catoms created prior to the selection are not affected. Catoms
created singly, from a model, or from prism dimensions will be centered on
lattice points; catoms loaded from world files as stamps may not be (depending
on the lattice of the world file they are loaded from; e.g., loading a hex planar
world file as a stamp into a hex planar world will result in all catoms aligned
properly, while loading a cubic world file into the same world may not). The
catom cursor also remains centered on a point in the chosen lattice.
Note: the lattice type of a world file is only a property of the catoms'
positions. It has no bearing on the featuremap assigned to the catoms by the
experiment file when an experiment is run.

Move origin:
Toggling this button and then clicking on the viewport moves the "origin" of the
worldfile to the location of the catom cursor by subtracting the coordinates
of the catom cursor from the coordinates of each catom in the world. 

Catom Cursor:
The first catom cursor toolbar allows the user to select mode and catom color.
The current mode is shown by the depressed toggle button, and the current color
is shown by the color of the fifth (color selection) toolbar button. Changing
the catom color affects all catoms created AFTER a new color is selected;
previously placed catoms are unaffected.
The second toolbar allows the user to switch the mouse wheel's function between 
"Camera Z" and "Cursor Z". "Camera Z" sets the scroll wheel to control the
position on the Z-axis (height) of the camera. "Cursor Z" sets the scroll wheel 
to control the height of the plane on which the catom cursor will appear; this
is useful for positioning catoms at arbitrary points in 3D space.

Catom GUIDs:
The textbox in this section displays the GUID of a selected catom. In order to
see a catom's GUID, left click on it in selection mode and the GUID will appear
here. To change a catom's GUID, select it and replace its GUID in the textbox
with the desired GUID. If this GUID is taken, you will be asked you want to
continue; if you choose to continue, the catom you selected and the catom with
the desired GUID will trade GUIDs.
Also in this section is the "Reset GUIDs to 1..n" button. This button will set
the GUIDs of all n catoms to the integers 1 through n, inclusive.

World Stamp:
The textbox in this section shows the source of the current stamp (or nothing
if there is none). If the source is a world file, it will show the path; if it
is a 3D model or a catom prism, a message to this effect will be displayed.
Clicking the "Stamp File" button allows the user to select a world file from
which the stamp should be created.
Toggling the "Stamp Mode" button toggles stamp mode (see "Stamp Mode" above).

Creation Settings:
These settings will be applied when catom groups are created from 3D models or
from prism dimensions.
Shell/Solid- if "Shell" is selected, a 2-catom shell will be created around the
model, and then an additional layer of catoms will be created on the inside of
this shell. The thickness of the second layer is determined by the shell
thickness specified in the textbox below.
Other Options-
"Flip YZ" exchanges the X and Y coordinates of the model or prism before is is
reproduced in catom form.
"Create as Stamp" specifies whether the model should be created immediately at
the origin (when the button is not depressed) or whether the model should be
created as a stamp which can then be positioned by the user in stamp mode.

Create from Model:
To select a model file for conversion to a catom group, click the "Model File"
button. The builder currently supports .obj and .stl (ascii and binary) files.
.stl files are preferable; in particular, .stl files are much more likely to be
convertible to solid models, as this file format is less leak-prone than .obj.
The size of the group to be created can be specified using the "Long Axis Size"
textbox. This number determines the length, in catoms, of the longest side on
a rectangular prism containing the model and  aligned with the X, Y and Z
axes. In practice, a higher number produces a larger model. The aspect ratio of
the model is always (approximately) preserved.
Clicking "Import/Create Object" will either create the model in accordance with
the settings and place it near the origin, or will create the model as a stamp.

Create catom prism:
To create a catom group in the form of a rectangular prism, enter the width (x)
depth (y) and height (z) of the prism (units: catoms) and click
"Create Prism". This will either create the prism in accordance with the 
settings and place it near the origin, or will create the prism as a stamp.

Info display:
Near the bottom-right corner, the catom cursor's coordinates and the number of
catoms in the world are displayed.

Clear all:
clears the world of catoms.

Save as:
Click "Save as" to save the current world. You will be prompted for a filename;
you may end the filename with ".world" or, if you do not, it will be appended
automatically.

*******************************************************************************