QuickFlash Slicer Example Program

By Nathan C. Hearn
   December 5, 2008


1. Introduction

This program generates images from 2D data files and slices from 3D data 
files for single datasets.  The populate_grid function illustrates the use 
of the QuickFlash::Slice::slice_simple function (see 
QuickFlash/src_lib/quickflash_slice_slicer.cpp) for extracting regularly 
spaced samples through the simulation volume.

The slicer program can be generated by calling "gmake slicer" in this 
directory.


2. Running the Program

The slicer has only two required arguments: the name of the dataset to be 
sampled, and one or more Flash data files.  To extract a slice of the 
dataset "dens" from the file mysim_hdf5_plt_cnt_0015, you can run

slicer dens mysim_hdf5_plt_cnt_0015

This command will produce the file mysim_hdf5_plt_cnt_0015_dens.csv, which 
is an ASCII file containing a space-separated matrix of the sampled values 
from the dataset.  (This file also includes a header that describes the 
operations performed.)


3. Program Options

By default, the slicer will choose a slice plane that intersects the center
 of the volume and is parallel to the x-y plane.  The resolution will be the 
same as the finest resolution in the AMR grid.  To change the behavior of 
the slicer, there are a number of options that can be used; by running the 
slicer without any arguments, the list of options will be displayed.

The current options are as follows:

--slice-center=CENTER_X,CENTER_Y[,CENTER_Z]

A comma-separated set of coordinates to be used as the center of the slice 
grid.  For 2D datasets, only the x- and y- values are given.

--slice-grid-width=GRID_X_WIDTH,GRID_Y_WIDTH

The width and height of the slice grid in the units of the simulation.

--slice-grid-pixels=GRID_X_PIXELS,GRID_Y_PIXELS

The number of pixels along the grid's width and height.

--rotation=[ROLL_ANGLE,POLAR_ANGLE,]AZIMUTHAL_ANGLE

Rotation angles (in degrees) for the slice plane about its center.  For 2D 
datasets, only the azimuthal angle is given.  For 3D datasets, the order 
of operations are: 

1. Rotate the slice grid about the +z-axis by ROLL_ANGLE
2. Rotate the slice grid about the +y-axis by POLAR_ANGLE
3. Rotate the slice grid about the +z-axis by AZIMUTHAL_ANGLE

In this scheme, the polar and azimuthal angles are the same as those of 
the standard spherical-angle coordinate system.  The roll angle effectively 
rotates the slice grid about its own normal vector.

--z-samples=NUM_Z_SAMPLES,Z_WIDTH

For each pixel, average over a distance (Z_WIDTH) normal to the slice 
plane.  The sample region is centered about the pixel on the plane, and 
the number of uniformly spaced samples is given by NUM_Z_SAMPLES.

--subsamples=SUBSAMPLES_X,SUBSAMPLES_Y

Within each pixel, compute the average of a uniformly spaced grid of 
subsamples.  The number of samples along the pixel's width and height are 
SUBSAMPLES_X and SUBSAMPLES_Y, respectively.  If the --z-samples option is 
also used, each sample normal to the plane will be computed using a 
subsample grid.

--output-prefix=OUTPUT_PREFIX

Prepend OUTPUT_PREFIX to the output file names.

--output-suffix=DESCIPTIVE_SUFFIX

Append DESCRIPTIVE_SUFFIX to the output file names.  (Appears before the 
file type extensions.)

--compute-symmetry=horiz|vert

Compute the odd- and even-symmetry of the slice across its horizontal 
(horiz option) or vertical (vert option) center.  The output from this 
option will also be a set of slices.

--image-type=FILE_EXTENSION

(ImageMagick only.)  Produce an image using a format that corresponds to 
the file name extension FILE_EXTENSION (e.g., "png").

--colormap=COLORMAP_FILENAME

(ImageMagick only.)  Use the specified colormap when producing the image.

--rescale-colormap

(ImageMagick only.)  Rescale and recenter the given colormap to the range 
of values in the slice.

--symm-map-range[=CENTER_VALUE]

(ImageMagick only.)  Similar to --rescale-colormap, but forces the center 
of the colormap to be at a given value.  (By default, the center is zero.)  
Currently, this option only works with linear colormaps.

--logscale

(ImageMagick only.)  Use a logarithmic progression for the colormap.

--show-colormap

(ImageMagick only.)  Include a colormap legend on the slice image.

--save-colormap[=LENGTH,WIDTH]

(ImageMagick only.)  Produce a separate colorbar image.  The length and 
width values (in pixels) are optional.

--horizontal-colormap

(ImageMagick only.)  Orient the colorbar produced by --save-colormap so 
that its length is oriented horizontally.  (By default, the colorbar is 
vertical.)

--save-colormap-info

(ImageMagick only.)  Produce a text file describing the colormap used for 
the slice image.

--image-only

(ImageMagick only.)  Produce an image file, but not the .csv text file of 
the slice data.

--transpose-image

(ImageMagick only.)  Transpose the generated image.

--save-image-metadata

(ImageMagick only.)  Produce a text file describing the image generated.

--empty-value=VALUE

Value to be used for slice pixels that fall outside of the simulation volume.

--buffer-size=BUFFER_SIZE

Size of the read-ahead buffer (in blocks) used by QuickFlash.

--cache-size=CACHE_SIZE

Size of the cache (in blocks) used by QuickFlash.

--quiet

Do not produce console output except error messages.

--

Do not treat any following arguments as options.
