 |
|
|
||||||||||||||||||||
|
|
|
||||||||||||||||||||
|
|
|
||||||||||||||||||||
|
|
|
||||||||||||||||||||
|
ParVox 3.0 TutorialLast Modified: March 10, 2005 © Copyright 1998-2005, California Institute of Technology Contents
[0] IntroductionThis is a tutorial on ParVox 3.0 volume rendering system, developed at the Jet Propulsion Laboratory. ParVox is made up of several components: the GUI xmparvox, the remote renderer front-end netparvox, the ParVox API, libparvox, and NetCDF input/output handling API, libvlmeta. In the pipeline mode, there are two additional modules: inparvox, the data input module, and outparvox , the image output module. This tutorial will walk through the installation procedure of the software, to run the existing GUI based rendering system, to generate NetCDF data files that are compatible with ParVox, and to write applications using the ParVox API. [0.1] Getting the SoftwareParVox 3.0 will be released via OpenChannel Foundation in April 2005. If you're interested in obtaining ParVox 3.0, please contact Peggy Li.[0.2] System RequirementYou'll need at least the following hardware and software:
The ParVox renderer has been tested on SGI Origin, SGI Altix, and Linux Beowulf clusters. The GUI has been tested on SGI Irix, Sun Solaris, Linux/x86 workstations and Mac OS X. The ParVox GUI requires a 24-bit color X server. On some systems with multiple color depth X servers, notably the Suns, the default visual must be set to 24-bit TrueColor visual. ParVox also requires netcdf-3.4 library. You may get netcdf-3.4 tar file from ftp.unidata.ucar.edu:/pub/netcdf through anonymous ftp. [1] InstallationTo unpack the parvox source, use:
This will extract the source into it's own directory, ParVox/. The following subdirectories will be in the ParVox/ directory:
Now cd into the newly created ParVox/ directory and do the following:
By default ParVox will install into the ParVox/ directory, with executables in bin/ and libraries in lib/. To install elsewhere, just copy the executables from bin/ to the desired directory. [2] Input Data Formatxmparvox and netparvox expect data to be in the NetCDF format. The stuctured grid and unstructured grid data have different meta data information and different file extensions. In addition, ParVox GUI allows user to save its rendering parameters into an environment file, which can be loaded back in the a future ParVox run. The environment file is also in NetCDF format. The default extensions for the ParVox input files are listed as follows:
[2.1] Meta Library FunctionsThe Meta library allows the user to easily create, read and write the ParVox input data files and environment files. The Meta library, libvlmeta, contains the following functions: [2.1.1] For Regular Structured Grid DatasetA regular structured grid dataset, also called voxel data, has file extension .vox.nc. The voxel data is stored as 3 dimensional array with one time step per file. The meta data contains the following information:
netcdf oceanvec0009.vox {
dimensions:
idim = 640 ;
jdim = 624 ;
kdim = 37 ;
num_vars = 1 ;
range_span = 2 ;
max_var_name = 20 ;
variables:
float range(num_vars, range_span) ;
char var_name(num_vars, max_var_name) ;
float nodata(num_vars) ;
float voxel(num_vars, kdim, jdim, idim) ;
// global attributes:
:spacing = 1.f, 1.f, 2.f ;
:byte_per_voxel = 4s ;
:time_tag = 9s ;
data:
range =
0 , 201 ;
var_name =
"velocity" ;
nodata = 0 ;
}
The functions to access a voxel data file are:
[2.1.2] For Unstructured Grid DataA unstructured grid dataset is stored in two files, a grid definition file and a set of data value files, one per timestep. ParVox currently supports data represented as tetrahedrons only. In a grid definition file, there are two two-dimensional arrays -- the vertex array, a nx3 array where n is the number of nodes, contains the [x,y,z] location of the vertex, and the cell array, a mx4 array where m is the number of cells, contains the vertex indices for each cell. A grid definition file has an extension ".ugrid.nc". In addition, a grid definition file contains the following metadata:
Following is a sample header from a grid definition file: netcdf landers.ugrid {
dimensions:
num_vars = 3 ;
num_vertices = 257850 ;
num_cells = 1400198 ;
verts_per_cell = 4 ;
vert_dim = 3 ;
range_span = 2 ;
max_var_name = 20 ;
variables:
float range(num_vars, range_span) ;
char var_name(num_vars, max_var_name) ;
float vertex(num_vertices, vert_dim) ;
int cell(num_cells, verts_per_cell) ;
// global attributes:
:spacing = 1.f, 1.f, 1.f ;
:cell_type = 0s ;
:time_tag = 1000s ;
:boundingbox = -500.f, -480.f, -60.f, 500.f, 520.f, 0.f ;
data:
range =
-10, 10,
-100, 100,
0, 30 ;
var_name =
"1st-Invar",
"2nd-Invar",
"3rd-Invar" ;
}
A data value file for a unstructured grid dataset contains the variable values on the vertices. ParVox always assume that the variable values are associated with the vertex, not the cell. If a dataset contains data at the center of a cell, it has to be interpolated onto vertices first. A data value file may contain multiple variables and it contains one time step per file. It has the same prefex as its grid definition file followed by a fixed number of digits representing the frame number and an extension ".ugval.nc". Following is the header of a data value file corresponding to the grid definition file shown above: netcdf landers371.ugval {
dimensions:
num_vars = 3 ;
num_vertices = 257850 ;
num_cells = 1400198 ;
verts_per_cell = 4 ;
vert_dim = 3 ;
range_span = 2 ;
max_var_name = 20 ;
variables:
float range(num_vars, range_span) ;
char var_name(num_vars, max_var_name) ;
float value(num_vertices, num_vars) ;
// global attributes:
:spacing = 1.f, 1.f, 1.f ;
:cell_type = 0s ;
:time_tag = 371s ;
:boundingbox = -500.f, -480.f, -60.f, 500.f, 520.f, 0.f ;
}
The ParVox functions to access an unstructured grid dataset are:
[2.1.3] For an Environmental FileAn environment file contains all the rendering parameters and transfer functions for a specific dataset, including a transformation matrix, the isosurface definition if any, the lighting parameters, the colormap and the opacity map. An environment file can be saved from the ParVox GUI. It can be reloaded into the ParVox GUI to restore the viewing position and data classification from a previous session. A environment file is a NetCDF file with an extension ".env.nc". The following information is included in the file:
A sample header of an environment file for a structured grid data set is as follows: netcdf ichiro1.env {
dimensions:
num_vars = 1 ;
cmaps_size = 768 ;
num_cmaps = 1 ;
opacs_size = 256 ;
num_opacs = 10 ;
map_dim = 2 ;
num_surfs = 8 ;
surface_fields = 6 ;
mat_fields = 4 ;
num_lights = 5 ;
light_fields = 4 ;
variables:
char colormap(num_cmaps, cmaps_size) ;
float opacity(num_opacs, opacs_size) ;
short map(num_vars, map_dim) ;
float surface(num_vars, num_surfs, surface_fields) ;
float material(num_vars, mat_fields) ;
float light(num_lights, light_fields) ;
char light_enabled(num_lights) ;
// global attributes:
:filter_type = 1 ;
:screen_width = 768 ;
:screen_height = 768 ;
:block_per_pe = 2 ;
:block_idim = 128 ;
:block_jdim = 128 ;
:block_kdim = 37 ;
:nodata_color = 1.f, 0.f, 0.f, 0.f ;
:translations = 5.f, 2.f ;
:scale_factors = 1.f, 1.f, 1.f ;
:zoom = 0.58000016f ;
:trans_matrix = 0.83481598f, 0.049714163f, 0.5482915f,
0.f, -0.3772499f, 0.77700859f, 0.50394195f, 0.f,
-0.40097129f, -0.62753302f, 0.66741246f, 0.f,
0.f, 0.f, 0.f, 1.f ;
:file_type = 0 ;
:outputfile = "parvox" ;
:num_iso_tbl = 2s ;
}
The functions to access an environment file are:
[2.2] Writing Data Conversion ProgramsWhen writing a program to convert existing data files to ParVox format, follow these steps: This will create a data file with the filename passed to vlmput_voxel4d(). If the filename does not contain the extension .vox.nc, it will be added on by the function. The normal practice is to create filenames with a base name and the timestep. For example, suppose we have a wind velocity dataset we want to create, we could name the files wind000.vox.nc, wind001.vox.nc, and so forth. [2.3] Example Data Conversion Programconv.c is a sample data conversion program. This sample program is designed to read in one timestep of a 128 x 128 x 128 volume, the volume containing one variable, density. The original data file was raw four byte float organized in the same order as ParVox, so we just read the file directly. We then walk through the data and do any necessary conversions. We also keep track of our minimum and maximum values in order to set the v4d.range[][] variables. [3] Using xmparvoxxmparvox is the graphical user interface that runs on the workstation. It works in concert with netparvox, which runs on the parallel machine and calls the rendering API in response to xmparvox controls. The order is important when running xmparvox and netparvox. The program that is started first becomes the server, while the other one assumes the role of client (see also [4] Using netparvox). To run xmparvox, use: The -server hostname should be used when netparvox is started first. hostname is the name of the host that netparvox is running on, N is the port number that netparvox is listening on. If -server host is not specified, xmparvox assume the server role. If the port is not specified, then xmparvox will use SERVER_PORT from vlnet.h as the port number. This value is defined to be 6543 in the standard ParVox distribution. If the workstation running the GUI does not have enough physical memory to buffer all the desired animation frames, use -diskbuf buffer_file to buffer animation images to disk filename buffer_file. Note this can cause a significant slow down of animation playback if the disk access is slow. Once xmparvox successfully connects to netparvox, it'll display its main window. There are four main areas in the GUI: Menu Bar, Command Panels, Image Display, and Message Panel. The Menu Bar is across most of the top of the GUI. The Command Panels will appear on the left 30% of the GUI. On startup this portion of the GUI is empty except for the ParVox logo. The Image Display is the big black area that dominates the GUI. This is where all the rendered images will be displayed. Finally, the Message Panel is under the Image Display. This is the area where transient messages will be displayed. [3.1] Menu BarThe menu bar has the following options: [3.2] Command PanelsThe GUI will put up different command panels on the left side in response to different user actions. These panels provide the user with various settings and controls for manipulating and rendering the volume. In most of these panels, there are Apply buttons which will send the new settings from that command panel onto netparvox and request a new image. Pressing these buttons are unnecessary if Autorender is set. [3.2.1] SliceThe user can select the variable(s) to render, and up to 8 slices per variable. Each selected slice must be perpendicular to the x, y, or z axis, and it can be selected via the radio buttons under Direction. The next three sliders and text boxes allows the user to select the starting and stopping point along the chosen axis for the slice, and the opacity of this slice. If the opacity value is set to zero, the opacity map set in the Volume Panel will be used to determine the voxel opacity in the slice. The Enable toggle button allows a user to turn on and off a slice for rendering purposes. Note: settings for disabled slices will not be saved when the user saves an environment. The Apply button sends the settings to netparvox and requests a new image. [3.2.2] Iso SurfaceUser can select variable/surface similar to Slice, above. For each variable/surface, the user can set the threshold for the surface, its opacity, and its thickness. The Display toggle button behaves the same as the Enable toggle in the Slice Command Panel. The Material Shading button will switch the panel to the Material Shading Control Panel. Finally, the Apply button sends the settings to netparvox and requests a new image. [3.2.3] Material ShadingUser can select the material properties for the isosurface being edited. The Restore button restores the properties to the values when the user first invoked this panel. The Done button saves the material property within the GUI and returns to the Iso Surface command panel, but does not send it to netparvox yet. The user must use the the Apply button in Iso Surface command panel (or autorender) in order to send the new settings to netparvox and receive a new image. [3.2.4] Volume
User can select a variable to render as volume. The Colormap shows the current colormap corresponding to the data range. The Opacity shows the current opacity values over the same range. The range can be modified by entering values in Lower Range and Higer Range text boxes. After the range is set, click on UpdateRange. Both the data range for Colormap and Opacity map will be changed. The Edit Colormap/Opacity button spawns an icol process. Note: an instance of icol is started every time the Edit Colormap/Opacity button is pressed. Therefore it is not a good idea to click on this button repeatedly. If multiple instances of icol are running, then the most recent change by any of the instances will be used. Icol can be a bit difficult to use, so there is a separate Icol Tutorial. The Update Colormap and Update Opacity buttons update the corresponding map by using the temporary file created by icol. Update Opacity only uses the red channel of the colormap being edited by icol. Therefore the user only needs to use the red channel to create an opacity curve. Reset Default resets both maps to ParVox system default. Apply sends all of this to netparvox and requests a render of the volume. [3.2.5] LightUser can select up to 5 point lights located at infinity. The toggle in front of each light specification enables/disables that light. The X, Y, and Z specifies the direction where the light points. The Intensity sets the intensity of the light. OK sends all the lights to netparvox and rerenders. [3.2.6] Bounding Box
[3.3] Dialog Windows[3.3.1] Load Data
Enter the data file name and path to be loaded by netparvox in the Filename field. The data must be accessible by netparvox, and the path is relative to the directory where netparvox was started from. To load multiple timesteps, use a filename of the format ``basename####''. For example, to load a series of data files named landers000.ugval.nc to wind030.ugval.nc in the directory /tmp1/peggy/GEM/parvox, the user would enter /tmp1/peggy/GEM/parvox/landers### in the Filename text field. The user then selects timesteps toggle and enter the timestep range and the interval between each timestep. The image on the left is a dialog box for unstructured grid input dataset. Note the grid definition file named landers.ugrid.nc will be loaded first. No file extension should be given in the Filename field. The default extension will be added automatically. For structured grid data set, the user can define how data is distributed by netparvox over the processing elements. The user can either specify Blocks/PE or the size of each data block in idim × jdim × kdim. If Blocks/PE is not zero, it will override the block size selection. The Raw and NetCDF toggles select the type of data file format being read in. In the current version of ParVox, only the NetCDF format is supported. However, on some machines the binary format may be faster. Use the nc2raw utility to convert NetCDF format data to raw format. The image to the right is a input dialog box for the unstructured grid dataset. The default file extension for structured grid dataset is .vox.nc if not specified. [3.3.2] Load/Save EnvironmentThe Load Environment and Save Environment dialog boxes are very simple. They have just one text field where the user enters the name of the environment file to load or save on the local workstation. Note: the environment file is saved to the local workstation that is running xmparvox, not to the remote netparvox side. The environment file is saved with the filename entered in the dialog box plus the .env.nc extension. [3.3.3] Output SizeThe Output Size dialog box allows the user to select the image size to render. The dialog box provides the user with several predefined sizes, as well as an option to use the current GUI window size and a user defined size. The change in size will take effect starting with the next rendered image. [3.3.4] AnimationThe Animation dialog box has four control buttons (in order appearing in control panel): 
When netparvox completes all of the time frames, the GUI will replay the rendered image frames in a loop if Animation Loop Playback toggle is on. Note: the GUI buffers all of the rendered frames locally on the workstation. This can cause local memory to be used up very fast, so be careful. Use the [-diskbuf buffer_file] option to xmparvox if you need to buffer to disk. The user can also specify a range of frames to animate. By default ParVox will animate all the loaded timesteps. By changing the Start and Stop values, a subset of the timesteps can be animated. The Done button will stop the animation and close the dialog box. [4] Using netparvoxnetparvox is the ``remote'' renderer that runs on a parallel machine. Version 3 of ParVox supports two renderers, netparvox for regular structured grid and netparvox_ug for unstructured grid. The regular structured grid renderer runs in pipeline and non-pipeline mode. The unstructured grid renderer only works in pipeline mode. The names of the executables for these three different modes are: The GUI xmparvox and the renderer netparvox communicates via ASCII commands over the network socket connection. The commands are documented in net_interface(5) man page. [4.1] Non-PipelineTo run netparvox in non-pipeline mode, use:If the option -server hostname is specified, then netparvox will act as a client and connect to a GUI acting as server on hostname. If this option is not specified, netparvox will act as a server and listen for a client connection. The option -port N specifies the port number to use for for connecting to the GUI. If -port N is not specified, netparvox will use SERVER_PORT from vlnet.h as the port number. This value is set to 6543 in the standard ParVox distribution. The -preload option is for preloading data. If specified, netparvox will preload the specified data file(s) before listening for the GUI connection. The parameter to -preload are the same as the fields in the Load Data dialog window of the GUI. The dtype is the data type: 0 means raw data, and 1 means NetCDF data. NetCDF data format is the only officially supported ParVox data format for this version. The -prefetch option is for prefetching data for out-of-core rendering. When specified, only frames number of frames will be loaded into memory when the input data are loaded. Input files beyong frames number of timesteps will be loaded one frame at a time during animation. Once netparvox completes initialization, it will wait for a connection from the GUI if -server was not specified. At this point, it will print out ``Go for it''. The user can then start the GUI on the local workstation. If -server was specified, it will try to connect to the host specified by -server on the port specified by -port. [4.1] PipelineTo run netparvox in pipeline mode, inparvox, netparvox, and outparvox must be started at the same time using mpirun. On the HP Exemplar, the SGI Origin 2000, and the Linux Beowulf cluster running MPICH, mpirun can be invoked with a -f app-file command line option. Here are sample app-file for the tested platforms: Consult your MPI documentation for the correct way of running multiple processes with one mpirun call. On our Linux cluster, the entire cluster is behind node 0 under one IP address. In this instance IP Masquerading must be installed, and the renderer must act as the client while the GUI acts as the server (i.e. netparvox connects out instead of waiting for an incoming connection). Consult your system administrator regarding IP Masquerading. There are no command line parameters to inparvox, inparvox_ug and outparvox, and the parameters to netparvox_pipe are the same as the non-pipeline version. The parameters to is very similar to that of netparvox, please see the man page for netparvox_pipe_ug. [5] Sample Interactive SessionHere's a sample interactive session using xmparvox and netparvox. Hopefully this will help the reader get a feel for the order of events. %qsub -I -V -lncpus=16 -lwalltime=00:30:00 [6] Using ParVox APIThe rendering portion of ParVox is implemented as an API library. This means the users can write their own programs to render images. main.c is an sample program that reads an environment file saved by the GUI and renders the images. This program is used to render in batch mode once the user has selected a desired view with xmparvox. It is also an example of how to call the ParVox API directly. For more detailed description of the ParVox API, refer to the ParVox API Manual. |
|
||||||||||||||||||||
|
|
|
||||||||||||||||||||
|
|
|
||||||||||||||||||||
|
|
|
||||||||||||||||||||
|
|
|
||||||||||||||||||||
|
|
|
||||||||||||||||||||
|
|
|
)![[]](images/stop16.gif)
)
/
)
)
