SUI: A Starsplatter UI Project

SUI Manual

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.

Project Menu | Data Menu | History Menu | Image Menu | Movie Menu

Dependencies
The dependencies for SUI are as follows.

    Perl 5.6.0 or higher.
    Tk-800.24 or higher.
    StarSplatter1.1
    A non-interactive, tiff to pnm converter. I recommend tifftopnm from the netpbm package, but other converters can be used, with varying results.

.suirc Configuration

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.

Compression:
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

Example:

    1CP%gzip%gunzip%gzip%.gz%

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.
Example:
    TTP%tifftopnm CAN > CAN.pnm%

Utility Bar

Project Menu

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.

Data Menu

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 Preview button is enabled.
    Release:Releases data file which disables the Preview button.
    (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 file.
    Compression:Sub-menu listing data compression formats. The format that is selected 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.

History Menu

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.

Image Menu

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 right.

Movie Menu

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.

About Menu

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.

UI Sections
Actions

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 display:

     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 in degrees.

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.

Camera

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.

Animation

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

Preview

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.

Star Bunches

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 box.
     Edit: Displays the selected star bunch's attributes in the star bunch fields.
     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.

Renderer

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.

Animation Engine
      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 below:

     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.

File Formats

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.

All documentation, code, and media on this site (c) Sean Maxwell 2002 unless otherwise stated.