The manual for SUI contains descriptions and detailed information on each part of SUI.
To start using SUI the quickest, it is best
to read through the tutorial while using the manual as a reference for each concept you
become curious about.
The tutorial can be done
in about 15-30 minutes depending on machine speed and user familiarity with machine and concepts.
The dependencies for SUI are as follows.
Perl 5.6.0 or higher.
Tk-800.24 or higher.
A non-interactive, tiff to pnm converter. I recommend tifftopnm from the netpbm package, but other converters can be used, with varying results.
General Load Commands are of the form:
TAG%ssplat load%[binary|ascii] [xyzxyz|xyzdkxyzdk]%[-skiplines n | -skipbytes n]%
They can be edited to load custom format particle files. Leave all % characters in their relative
positions, as they are used for delimiting purposes. Here is an example of an edited load command:
3LC%ssplat load%binary xyzdkxyzdk%-skiplines 10%
skiplines and skipbytes are number of lines or bytes to skip at the beginning of the file. xyzxyz and
xyzdkxyzdk describe the format as triples xyz or fiveples of xyz-density-exponent constant.
The compression section configures SUI to use the types of compression you are using on
your system. The format is:
TAG%NAME%DECOMPRESS COMMAND%COMPRESS COMMAND%EXTENSION ON SYSTEM
You should never change the TAG. It is used to locate the lines in the .suirc file.
The tiff to pnm converter on you system needs to be defined in the .suirc file. By default SUI
is configured to use tifftopnm from the netpbm package. If you want to use a different tiff to pnm
converter, you must specify the command here. The command has to convert CAN(a tiff file) to CAN.pnm.
TTP%tifftopnm CAN > CAN.pnm%
The first menu on the tool bar. It is used in conjunction with the entry field to its right.
When clicked, the Project Menu has four options:
New Project: Create a new project with all values initialized to default.
Open Project:Open a project with the name entered in the entry field.
Save Project:Save project to name in entry field.
Exit: Exit SUI in a clean fashion, by deleting all temp files.
The second Menu on the tool bar. It is used in conjunction with the entry field to its right.
When clicked, the Data Menu has two options and two sub-menu:
Load: Checks to see if file exists as specified
in the entry field. If so the
button is enabled.
Release:Releases data file which disables the
(note: Enabling/disabling the preview button is
a feature that helps let the user know if a valid data
file is in use.)
Format:Sub-menu listing valid data formats. The format that is selected
will be used when reading from the open data file. The formats
General I, II, and III are custom formats defined in the .suirc
Compression:Sub-menu listing data compression formats. The format that
will be used when reading from data files. By default, gzip,
and bzip2 are configured as the first two formats, a generic
example as the third, and then the last two are un-configured.
All five options are configurable from the .suirc file. The
instructions for doing so are detailed in the .suirc file.
The third Menu on the tool bar. When clicked, the History Menu has two options:
Delete Last: Deletes the most recent entry in the history.
Clear History: Deletes all entries from the history.
The forth Menu on the tool bar. When clicked, the Image Menu has one option:
Save: Save the image with the name specified in the entry field to its
The last Menu on the tool bar. When clicked, the Image Menu has three options:
Make Script: Generates a movie script based on the history of the project.
This will output errors to stdout, so if the user is following
in a terminal he or she can see if any problems occur. This only
generates a temporary file called temp_sui_movie_file. Use
the next function to save the script.
Save Script: Saves the generated script as the name in the entry filed
concatenated with ".tcl". User can specify a path to a file
in the entry field if desired.
Run Script: This simply executes StarSplatter on the script named in the
entry field. This may not be particularly useful, but it will
really depend on the users needs.
The About menu has three options:
SUI:Provides information about SUI and dependency authors.
Warranty:Displays GPL warranty information.
Distribution:Displays the GPL distribution information.
The Actions tool set is a set of three Action buttons, three entry fields, and
three check buttons. From top to bottom, the Action buttons are Move, Pan, and Rotate.
The three entry fields are in the same order and each has the following format:
Move: "X-coordinate Y-coordinate Z-coordinate".
All three floating-point numbers.
Pan: "X-coordinate Y-coordinate Z-coordinate".
All three floating point numbers.
Rotate: "Number-of-Degrees Axis-of-Rotation".
Floating point number and x|y|z.
The buttons numbered 1 through 3 are used to tie actions together.
Such an action would be a Move and Pan. To do this
the user would check button number 1. The function of all three buttons are:
Tie Move and Pan: Button 1.
Tie Move and Rotate: Button 2.
Tie Pan and Rotate: Button 3.
Once actions are tied together, the user only needs to hit one of the Action
buttons to perform the action. SUI checks to see if a change has been made to
coordinates before calculating, so if actions are tied, but one is not
changing, then only the relevant one is used. All three actions can be tied together.
Directly below the Move, Pan, Rotate block, are the Pos, At, and Rot fields. These fields merely
Pos: The current position of the camera in X Y Z format.
At: The current point that the camera is pointed to in X Y Z format.
Rot: The current amount of rotation around the x, y, and z axes
Below these is the Record button. When this check button is checked, all actions are recorded
in the history of the project. The Move d/10 button enables or disables the
padded move function
for animations. If checked, a step size of d/10 --where d is distance from the origin of the
coordinate system-- is used for moving in the space of the model. If unchecked, a uniform step
size is used for all steps regardless of position in coordinate system. When a large move is made
that starts far from origin, but passes close(within a distance of 10), it is a good idea to use
d/10 movement. However, experimentation is probably best to determine which style is better
suited for each movement.
The Camera section contains the commands that determine how the camera will act in the model.
The properties are:
Fov: The camera fovia angle. It is set to a default of 50.0.
HY: The hither and yawn for the camera. Hither is the near
distance inside which StarSplatter will ignore points,
and the hither distance is the distance beyond which the camera will ignore points.
Proj: The projection style of the camera.
Up:The axis that defines the up direction for the image.
The input in Animation provides data about data file format, and other aspects of animation.
Frames: The number of frames that will be generated to
perform the current action.
Continue During Action: If checked, then the model will progress
during each frame, if the proper data is input in the Range field.
Range: The format of the data file name(a formatted output string),
the first data file, the last file, and the increment amount.
The three numeric arguments should be integer values. An example would be:
DATA%04d 0 100 5
This would be a range of data files named DATA0000 through DATA0100, and SUI should only use every fifth
one. That means the frames should be set at 21 since SUI will use 0, 5, 10, ... , 95, 100.
If an improper range is given, then SUI will alert the user that the range is not valid for the increment
value, or the number of frames. After an action has been performed,
the Range is updated to have the first data file equal to the previous last data file, and the last data
file equal to the number of frames divided by
the increment value. In this example, if the number of frames was 20, then the updated Range would be:
DATA%04d 100 200 5
The Preview section contains the preview canvas and one button:
Preview:updates the preview window with an image generated using
most current data from all fields. The button is disabled until
data has been loaded with the Load button.
The most complicated portion of the UI, but it is very straight forward.
List Box: Contains a list of star bunches that have been added
+:Adds a star bunch using the values in the
star bunch fields.
-:Removes a selected star bunch from the list
Edit: Displays the selected star bunch's attributes in the star
Save: Applies changes made to a star bunch. Changes will not take
effect if the user does not save!
Name: The name of the star bunch. A dollar sign will be appended
to the name upon adding if one is not present.
Color: Four float numbers indicating the color of the star bunch
in Red Green Blue Opacity format.
E.C.:Exponent constant. This determines the splat size that
StarSplatter will render for particles in this bunch.
Dens: Density. The density of particles in this bunch.
Attributes of the renderer.
Exp:Exposure time for the image. Just like a real camera image,
the longer the exposure, the more saturation.
ERT: Exposure Rescale Type. Can have the value "linear" or "log".
Something to try changing for different results.
LRB: Logarithmic Rescale Bounds. If the ERT is log, you can alter
these to change results.
CO: Cut Off. The luminosity below which a point will not be rendered.
Size: The size of the rendered image.
Render Points: If checked, the renderer will not render splats,
just points. This is much faster if the user is just looking
for a good camera angle.
The animation engine is fairly simple. To make an animation, the user must
first set all of the parameters for rendering such that a viewable image
is being created if the user generates a preview. Then follow the steps
1. Check the rec button.
2. Set the Number of frames
by adjusting the slider.
3. Input the proper information into the
Range field. The user should make sure
the number of frames matches the info in the Range; however, SUI will
also check this before it writes the script.
4. Check Continue During Action if the model is
intended to progress
during the animation. By progress it is meant that each data file described
by the Range field will be loaded sequentially and used to render exactly
one frame, reaching the last data file on the last frame.
5. If you want to use the d/10 movement style,
make sure it is checked.
6. Now, set the fields in the Action section
to the values for performing the
desired action. Make sure to check the appropriate
Tie buttons if performing
multiple actions at the same time.
7. If all of the previous steps are complete, press the Action button that
applies to the action. If no errors are reported, then everything was
correct. If an error occurs, use the feedback to try and find the mistake.
SUI does a certain amount of error checking so that the user cannot
make NULL moves. It also checks for proper number of arguments in all
fields. However, it is not exhaustive. The user should try to make sure
all information is correct. It would be a good idea to read through the
StarSplatter Manual as well.
8. At this point, the Range will be updated to reflect the Action, and will
be ready to make another move of the same length of frames, and
continuing through the data files at the same rate. If another action is
to follow, go to step 2 and repeat. When no more actions are desired,
uncheck the "rec" button. Go to the
Movie Menu, and select "Make Script."
This will generate the tcl code to make the animation. To save the script
enter the name in the text field next to the Movie Menu, then select
"Save Script" from the Movie menu.
9. The final step is to run StarSplatter on the script. There is a command
in the Movie menu that will run StarSplatter on the movie script whose
name appears in the text field. It would be a good idea to move the script
to a directory by itself since the frames for the animation will be output
there. When run with StarSplatter, a sequence of PNM files will be
generated. These frame can be encoded into a movie using the proper utility.
The project files for SUI are named with a .sui extension. The user can rename these
with a different extension, or none at all if desired. However, the .sui file format is as
follows if there is a need or curiosity.
1. "sui standard ascii file"
2. Number of star bunches
3. Each starbunch followed by a new line. Number of lines equal to the number of star bunches
4. The current position of the camera.
5. The point the camera is currently looking at.
6. The degrees of rotation around the x axis.
7. The degrees of rotation around the y axis.
8. The degrees of rotation around the z axis.
9. The camera fovea angle.
10. The camera hither and yawn values.
11. The projection style for the camera.
12. The up direction for the camera.
13. The exposure time.
14. The exposure rescale type.
15. Log rescale bounds.
16. Cut off intensity for renderer.
17. Render points or not.(0 or 1)
18. Animation progress or not.(0 or 1)
19. Data file name.
20. File format.
21. Image size.
22. Move d/10 or not.(0 or 1)
23. Tie pan and Move?(0 or 1)
24. Tie pan and Rotate?(0 or 1)
25. Tie rotate and move?(0 or 1)
26. Record?(0 or 1)
27. Integer used for calculating temp names.
28. Integer used for calculating temp names.
29. Integer used for calculating.
30. The number of frames on slider.
31. Integer indicating if action has occurred.(0 or 1)
32. The data Range string.
33. The data file compression type.
34. The image name in Image menu text field.
35. The movie name in Movie menu text field.
36. The history of the project. Each action followed by a new line.