User Tools

Site Tools


Image Stacks in 3DVisualizer

Here is some basic information on how to view image stacks as volumes in 3DVisualizer

Image Formats

The best format for images is greyscale png files. jpg files can also be read, but they often have artifacts, so if your images are tiff or other format, convert them to png files. If they are in color and you read in a single image stack, 3DVisualizer will convert them to grey scale. If you would like to view confocal images with multiple channels, save each channel as a separate greyscale png image stack or if they are combined, you can use the -color option (see Upload Multiple Image Stacks below).

The image files should have some consecutive numbering scheme in the filenames. The most important thing is that the numbers are consecutive, the image stack reader is quite flexible with numbering formats.

Upload the stack of images

Upload your images to a directory on A good place to put them would be


Inside that directory, copy your images into a folder. (Help with copying files in UNIX: copying_files_in_unix)

Make a header file

If you are loading a single image stack follow these instructions. If you want to upload color images with each color as a separate variable or multiple channel data as separate image stacks, please see Upload Multiple Image Stacks

Make a header file describing the image stack that includes the size and number of images, the template of how to generate file names, etc. The format of the header file is a sequence of <tag>=<value> pairs, each on an individual line. Any spaces etc. in the tags and values and around the = are ignored. The header file should have the extension .shdr, and it's best to put it beside the directory containing the image files, and probably give it the same name (plus the extension).

Here are the tags recognized by the reader:

numSlices = <n>

n is the number of individual images in the stack.

regionOrigin = <x> <y>

x and y are the left and lower corner of a subimage to be extracted from each image in the stack. If not given, these default to 0 0.

imageSize = <x> <y>

x and y are the width and height, respectively, of a subimage to be extracted from each image in the stack.

sampleSpacing = <x> <y> <z>

z is the distance between slice images, or slice thickness, in “world units”, x and y are the horizontal and vertical distances between pixels in a slice, respectively. The actual units used are mostly irrelevant, but they have to be consistent, otherwise the volume will appear stretched. The units are only relevant when using the measurement tool; any positions and distances will be in whatever units are used for the sample spacing.

sliceIndexStart = <s>

i is the number used to generate the file name of the first image slice. If not given, it defaults to 0.

sliceIndexFactor = <f>

f is the increment in numbers between adjacent images. If not given, this defaults to 1 (consecutive numbers), but it can be any other integer to skip slice images when reading.

sliceFileNameTemplate = <t>

t is a template for generating slice file names given a slice index. (Include the path to the file.) It cannot contain any spaces. The template is a combination of a base name and a number, and a definition of how to format the number. First, slices are indexed from 0 to n-1 (where n is the number of slices). Then, the slice index i is converted into the file number by: number = s + i * f. The name template is a printf-style string; it uses a %d command to insert the number into the template. For example, if the template is Foo%dbar.jpg, then the generated file names are Foo0bar.jpg, Foo1bar.jpg, …, Foo10bar.jpg, …, Foo100bar.jpg, … assuming that s=0 and f=1. The %d command can be modified to generate different formats:

%d → plain number: 0, 1, 2, …, 10, …, 100, …

%0<x>d, where <x> is some integer → number padded to width <x> with leading zeros. %05d: 00000, 00001, …, 00010, …, 00100, …

… and a whole bunch of other formats that are probably irrelevant. Type “man 3 printf” to read all the details.

The regionOrigin and imageSize tags allow you to crop the image slices to any size, as long as the region is contained in every slice (otherwise loading fails). The best sizes to try are powers of two, because thats the only sizes OpenGL understands natively. 512×512 is a good first choice. You can also adjust the number of slice images to read by playing with the numSlices and sliceIndexStart tags.

Example File:

numSlices = 146
regionOrigin = 150 150
imageSize = 512 512
sampleSpacing = 10 1 1
sliceIndexStart = 1
sliceIndexFactor = 1
sliceFileNameTemplate = /share/Data/VolumeData/ls_0916_bw/ls0916_%d.png

Start 3DVisualizer

To view the images, run Visualizer with the following command line:

Visualizer -class ImageStack <path/header file name> [medianfilter] [lowpassfilter]

The ImageStack class recognizes two optional command line parameters, medianfilter and lowpassfilter. Both average between slices in different ways. Medianfilter is most important to remove brightness differences between slices; lowpassfilter can be used afterward to remove other noise. (Note that if you want to use the filteres, leave off the “[” and “]”; brackets indicate that the commands are optional.)

Create a Script

You can simplify loading 3DVisualizer by creating a command file or script. It's just a text file containing the Visualizer command line (minus the -class) with one argument per line. Call the file the same as the image directory/.shdr file, but with a .in extension. The contents:

<header file name>

Example Files

In case of doubt check out the existing .shdr and .in files in these directories:



Upload Multiple Image Stacks

Here are instructions for the new MultiChannelImageStack Visualizer module (e.g. for confocal images). All options are passed via the command line, so there won't be a .shdr stack header file as in the old ImageStack module. It was redundant, because you can get the same functionality using a .in input file.

Start the .in file with MultiChannelImageStack

Here are the module options:

* Stack format definition (these apply to all image stacks and can be supplied in any order, but before any image stack definitions):

-imageSize <width> <height>

Defines the width and height (in that order) of the region extracted from each image in each stack.

-numImages <number of images>

Defines the number of images in all stacks.

-sampleSpacing <pixel width> <pixel height> <slice distance>

Defines the voxel size of the image stack. The numbers are: width of a pixel, height of a pixel, distance between images in a stack, in that order.

* Image stack definitions, can be issued multiple times:

-regionOrigin <left> <bottom>

Defines the lower-left corner of the extraction region for all images in all following stacks. Initially set to (0, 0).

-imageIndexStart <first index>

The index number of the first image in all following image stacks. Initially set to 0.

-imageIndexStep <index increase>

The index number increase between adjacent images in all following image stacks. Can be set to a negative value to invert the stacking order of an image stack. Initially set to 1.


Applies a median filter to *only* the next image stack.


Applies a lowpass filter to *only* the next image stack.

-median and -lowpass can be combined, in which case the median filter is applied before the lowpass filter, regardless of the order of the options.

-greyscale <channel name> <image file name template>

Loads a stack of greyscale images into a single scalar variable of the given name. The name template must contain exactly one %d conversion operator, as in printf. Modifiers such as %04d etc. are allowed. Individual image names in the stack are constructed as follows:

- The image index counts from 0 to numImages-1 from the bottom of the stack to the top.

- The image number is computed as index*imageIndexStep+imageIndexStart.

- The image number is inserted into the file name template.

-color <red channel name> <green channel name> <blue channel name> <image file name template>

Loads a stack of RGB color images into three independent scalar variables of the given names. The file name template has the same format and function as in the -greyscale option.


-imageSize 1024 1024
-numImages 71
-sampleSpacing 210 210 310
-regionOrigin 0 0
-imageIndexStart 0
-imageIndexStep 1
-greyscale R /share/Data/VolumeData/Confocal/warland/FD11E01_JAM_7hr_a_1/R/jam-%d.png
-imageIndexStart 71
-imageIndexStep 1
-greyscale G /share/Data/VolumeData/Confocal/warland/FD11E01_JAM_7hr_a_1/G/jam-%d.png
-imageIndexStart 142
-imageIndexStep 1
-greyscale B /share/Data/VolumeData/Confocal/warland/FD11E01_JAM_7hr_a_1/B/jam-%d.png
keckcaves/imagestacks.txt · Last modified: 2012/06/13 18:00 by sumner