Welcome to OOF3D!
OOF3D is just like OOF2 but in
three dimensions. It calculates the physical properties
of three dimensional microstructures, basing the
calculations on three dimensional micrographs.
For the moment there is no manual for OOF3D, but its
operation is very similar to OOF2. You should be able
to learn to use OOF3D by reading
Manual. This page includes a summary of
the differences between OOF2 and
Although OOF3D is based on OOF2, many parts of it are
new, and we expect that there is the possibility that
there might be bugs in the software. Please
report bugs to the developers
OOF3D includes a bug reporting tool (in the Help
menu and the error dialog box) which we encourage you to
use if possible.
OOF3D is in
Download and Installation
OOF3D can be installed from source
on Linux and Macintosh computers.
A binary installer is available
for Macintosh only.
Please read the
Copyright notice before downloading
To see what's new, read the
OOF3D change log.
Installing from Source
version 3.2.1 (12641425 bytes, compressed; MD5
Install the OOF3D
prerequisites, which are
NOTE that the prerequisites for 3.2.0 and
later are different than for 3.1.2 and earlier.
3.2.0 requires a different version of vtk.
Go to the directory where you want to build OOF3D.
We'll assume it's called "oof3d", and is in your home
Unpack the downloaded archive. If the archive is
in a directory called "downloads" in your home
directory, you'd do that like this:
tar -xzf ~/downloads/oof3d-3.2.0.tar.gz
Adjust the directory name as necessary.
You should now have a directory called
oof3d-3.2.0 containing the oof3d source
code, installation scripts, and tests.
Go the the new oof3d source directory and read the
Build and install OOF3D:
python setup.py build --3D
python setup.py install --3D --prefix=xxxxx
where xxxxx is the directory in which you
wish to install OOF3D.
If you omit --prefix=xxxxx the
installation script will attempt to install
into a system directory, in which you might
not have permission to create files. You can
either run the installation command
which gives you permission to write system
files, or you can use --prefix to
install in a location where you have
permission, such as your home directory. In
that case, you may need to set environment
variables, as described in the README file.
If vtk isn't installed in the standard
location, perhaps because your system already
included vtk5.8 and you had to install 8.1.1
somewhere else, you'll need to use
the --vtkdir option:
python setup.py build --3D --vtkdir=/path/to/vtk
python setup.py install --3D --prefix=xxxxx
where /path/to/vtk is the directory
that contains include/vtk-8.1
and lib/libvtk*. Note that if there
are multiple versions of vtk in the same
directory, oof3d may get confused.
On Macs, OOF3D can be built to use Apple's
native graphics instead of X11 by
adding --cooca to the build command:
python setup.py build --3D --cocoa
This will only work if all of the
prerequisites have also been built for
If all goes well, you should have files called
"oof3d" and "oof3dtest" in the bin
subdirectory of the installation directory. If
the bin directory is in your PATH, you can
type oof3d to run the program. If not,
you can type the full name
(⟨prefix⟩/oof3d) or see the
README file and learn how to set PATH.
If something didn't work, read the README file
again. If that didn't help, send mail
Tell us exactly what you did, and what
went wrong, including all error messages.
Run the test suite by typing "oof3dtest". This is
optional, but can help to diagnose problems.
Beware that the full suite takes quite a while to
Binary Installation on Mac
With the binary installation, you don't have to install
any of OOF3D's prerequisites. However, because the
installer includes all of the prerequisites, it is large
and requires a lot of disk space (~800M). It may be
wasting space by installing copies of libraries that are
already present on your system.
The binary installer installs a version of OOF3D that
uses native Mac graphics, not X11.
(186729023 bytes; MD5
Double-click the installer and follow the
instructions. This will create a directory
Read the section on setting environment variables in
the README file, and
add /opt/oofports/bin to
your PATH. You can ignore the rest of the
Run OOF3D by typing oof3d in a Terminal
window. Optionally, run the tests by
typing oof3dtest. The tests take a long
time to finish.
If you didn't set PATH properly in the
previous step, you can still run OOF3D by typing
its full name: /opt/oofports/bin/oof3d.
OOF3D works basically the same way as OOF2, so you can
learn a lot about how to use OOF3D by reading
Manual. This section summarizes the main
differences between OOF2 and OOF3D. We hope that this
summary, the OOF2 manual, the OOF3D tutorials (in the
OOF3D Help menu), and a little experimentation on your
part will be sufficient to get you going with OOF3D
while the manual is being prepared.
--3D must be added to the build and install
OOF3D includes its own copy of swig, so it's
no longer necessary to either install it or to
use the --skip-swig flag.
Images are read from a directory which contains
multiple two dimensional image files, which will be
assembled into a three dimensional image. Each 2D
file contains one XY slice of the 3D image. The
files are stacked in the Z direction. If you prefer
a different orientation for the image, use the Flip
and/or Permute_Axes tools in the Image Modification
pane on the Image page.
The dialog box for loading images allows you to
select how the files are specified (all files in the
directory, file names matching a certain pattern, or
individually selected files) and how the files
should be sorted. (Alphabetical sorting
puts imagefile10.jpg before
imagefile9.jpg, while numerical sorting puts it
You can load an image at start-up by invoking oof3d
oof3d --image directory
where directory is a directory containing
image files. All of the files in the directory will
be loaded, sorted numerically, and the physical size
of each voxel will be 1x1x1.
The Graphics Window
The OOF2 Graphics Layer Editor window has been
eliminated. Instead, all of the attributes of a
graphics layer are specified in one dialog box,
which is opened in response to the Layer/New or
Layer/Edit menu items in the Graphics window, or by
double clicking on a layer in the layer list.
The Viewer toolbox in the Graphics window contains
detailed tools for manipulating the 3D view. Each
of the items in the upper part of the toolbox
(Camera Info, Translate, Rotate, Zoom, and Clip) can
be expanded or collapsed by clicking the triangle by
the item. Most of the data can be edited, but
Camera Info is just informational.
The bottom of the Viewer toolbox contains Prev and
Next buttons for navigating the list of previous
views (ie camera settings). It has a Restore menu
which contains predefined views (Front, Back, etc).
The current settings can be saved and named, which
adds them to the Restore menu. For convenience, the
Restore menu and the Prev and Next buttons are
duplicated (but unlabeled) in the upper right corner
of the graphics window, where they can be used even
when the Viewer toolbox isn't active.
The interpretation of mouse clicks in the graphics
window is determined by the active toolbox, but also
by the setting of the buttons above the drawing
area. Here Select means to perform the toolbox
operation. Tumble, Dolly, and Track change the
camera parameters. All operations use just the left
Layer ordering in 3D doesn't mean quite the same
thing as 2D. If objects are coincident, "higher"
layers will hide the "lower" ones. If they're not
coincident, the one nearer to the point of view
(camera) is visible.
The hardest thing about 3D visualization is seeing
the insides of things. OOF3D offers two ways of
seeing inside objects. One is to set clipping
planes in the Viewer toolbox. A plane is specified
by giving a direction and an offset from the origin.
The plane is perpendicular to the given direction.
The offset is the minimum distance from the plane to
the origin. You can use multiple planes at once.
Be sure to experiment with the "Flip" checkbox for
each plane, and the "Invert All" checkbox below the
list of planes. Clipping planes can be edited
interactively by selecting the plane in the list in
the Viewer toolbox, which causes the plane and a
normal arrow to be drawn in the graphics
window. Clicking and dragging the plane moves it in
the direction of the arrow. Clicking and dragging
the arrow reorients it and the plane by rotating
about the base of the arrow. Control-clicking and
dragging either the arrow or the plane moves the
arrow's base within the plane.
The second way of seeing inside objects is to apply
filters. All OOF3D graphics layers have a "filter"
parameter, which can be used to prevent parts of the
layer from being drawn. For example, when viewing a
Microstructure, it's possible to display only the
voxels in a given group, or only those with a given
Some of the Voxel Selection Modification methods in
the Voxel Selection page have an operator
parameter, which determines what the method does
with the voxels it's manipulating. This effectively
consolidates multiple OOF2 menu items into a single
OOF3D command. For example, OOF2 has "Select
Group", "Add Group", "Unselect Group" and "Intersect
Group", whereas OOF3D has only "Group", with an
operator that can be set to "Select Only", "Select",
"Unselect" and "Intersect", corresponding in that
order to the OOF2 commands.
Skeletons are constructed by dividing the
Microstructure into rectangular boxes, and then
dividing each box into 5 tetrahedra. The number of
boxes along each edge of the Microstructure is a
settable parameter. There are two ways of orienting
the 5 tetrahedra in each box, but compatibility with
neighboring boxes means that choosing the
orientation for one box determines the orientation
of all of the others. The two ways are called
"moderate" and "middling", to be analogous to OOF2's
ways of creating a Skeleton from triangular
Not all of OOF2's Skeleton modification methods
translate well to 3D. OOF3D includes a new method,
"Surface Smooth", which attempts to smooth the
interfaces between materials.
The predefined Skeleton boundaries have different
names in OOF3D. Rather than try to remember whether
the "Back" boundary is at x=0 or z=0, the boundary
names include the direction and "min" or "max".
Thus the face boundary called "Xmin" is at x=0, and
the edge boundary called "XmaxZmin" is at x=L and
As of version 3.2.0, the Skeleton selection methods
have an "operator" parameter, like the Voxel
selection methods do.
Fields can't be marked "in-plane", and there
are no in-plane constraint equations.
The Scheduled Output page has been simplified. It
has one list of outputs, instead of separate lists
for Outputs, Schedules, and Destinations. When
creating a Scheduled Output, all of its properties
are set in a single dialog box.
The Analysis and Boundary Analysis pages have been
merged. The functionality of the old Boundary
Analysis page is obtained by selecting a boundary as
the domain in the Analysis page.
The Scalar and Aggregate buttons on the Analysis
page have been removed. All Outputs are available
in a single set of menus.
Direct Output is not available on face boundaries,
because of the difficulty of defining the output
points. Instead, those domains only support
integrated output quantities. If you try to select
Direct Output and Face Boundary together, nothing
will be displayed in the Sampling widget and the Go
button will be insensitive.
OOF3D is still under development, and not all of its
planned features are implemented. Here are some of the
things that are missing but that we're planning to
include. This list is bound to be incomplete.
There is no tool for selecting the voxels underlying
a segment, face, or element.
Only left mouse clicks are recognized. (In a later
version the user will be able to configure the
meaning of different mouse buttons, so that one
button is always for selection and one for changing
the 3D view parameters.)
There is no graphical indication of which voxels are
active, although filters can be used to display only the
active or inactive regions.
3D EBSD data files can't be loaded.
PDF output doesn't work.
Automatic skeleton generation is not yet
Periodic boundary conditions are not yet
Materials can be assigned to voxels but not
directly to elements or element groups.
Adaptive mesh refinement is not yet implemented.
The Mesh Data viewer window isn't yet implemented.
The sample extensions have not yet been updated for
Please report problems
If possible, please use the OOF3D bug report tool, which
assembles all of the relevant information in one file
which you can mail to us. You can open the tool in the
"Help/Report Error" menu, or via the "Report" button in
the error dialog.
If you're unable to create a bug report file with the
bug reporting tool, please be sure to include the
following information in your e-mail:
- Your operating system and version number.
- The OOF3D version number.
A description of the problem, including what you
were doing when the problem occurred, as exactly as
Anything that will help us reproduce the problem.
An OOF3D log from the problem session. Save
the log file with the "File/Save/Python Log" menu
item, or with the "Save" button in the quit dialog.
Any input files (images, scripts, or data) that
Lots of operations need to be sped up, especially
graphics operations on large meshes.
The OOF3D GUI tests aren't portable. Failing a test
doesn't necessarily mean that the program or your
installation is broken. Try running the tests with
the --nocanvas option, as explained in the
The content of the graphics window sometimes doesn't
appear when it should. Resizing the window slightly
usually fixes the problem.
Active areas and unmeshable voxel groups aren't
stored properly in data files.
In the tutorials, using the "Back" and "Next"
buttons can desensitize the "Next" button, even if
the page's task has been performed. A work around
is to enable Debug mode in Help/Debug menu, then
click "Back" and "Next" again. In Debug mode, the
"Next" button is always sensitive.
The program often prints
Exception TypeError: "'NoneType' object is not callable" in ignored
when exiting. This is harmless and you can ignore
it. We know what causes it and how to fix it, but we
don't know where to fix it.
Disclaimer and Copyright
The research software provided om this website
("software") is provided by NIST as a public
service. You may use, copy and distribute copies of
the software in any medium, provided that you keep
intact this entire notice. You may improve, modify and
create derivative works of the software or any portion
of the software, and you may copy and distribute such
modifications or works. Modified works should carry a
notice stating that you changed the software and
should note the date and nature of any such
change. Please explicitly acknowledge the National
Institute of Standards and Technology as the source of
the software. To facilitate maintenance we ask that
before distributing modified versions of this
software, you first contact the authors at
The software is expressly provided “AS IS.” NIST MAKES
NO WARRANTY OF ANY KIND, EXPRESS, IMPLIED, IN FACT OR
ARISING BY OPERATION OF LAW, INCLUDING, WITHOUT
LIMITATION, THE IMPLIED WARRANTY OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT AND
DATA ACCURACY. NIST NEITHER REPRESENTS NOR WARRANTS
THAT THE OPERATION OF THE SOFTWARE WILL BE
UNINTERRUPTED OR ERROR-FREE, OR THAT ANY DEFECTS WILL
BE CORRECTED. NIST DOES NOT WARRANT OR MAKE ANY
REPRESENTATIONS REGARDING THE USE OF THE SOFTWARE OR
THE RESULTS THEREOF, INCLUDING BUT NOT LIMITED TO THE
CORRECTNESS, ACCURACY, RELIABILITY, OR USEFULNESS OF
You are solely responsible for determining the
appropriateness of using and distributing the software
and you assume all risks associated with its use,
including but not limited to the risks and costs of
program errors, compliance with applicable laws,
damage to or loss of data, programs or equipment, and
the unavailability or interruption of operation. This
software is not intended to be used in any situation
where a failure could cause risk of injury or damage
to property. The software was developed by NIST
employees. NIST employee contributions are not subject
to copyright protection within the United States.