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 the OOF2 Manual. This page includes a summary of the differences between OOF2 and OOF3D.

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 at [email protected]. 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 an Active Development status.

OOF3D can be installed from source on Linux and Macintosh computers.

Please read the Disclaimer and Copyright notice before downloading this software.

To see what's new, read the OOF3D change log. If you need an old version, you can get it from the archive.

Installing from Source

1. Download OOF3D version 3.2.4 (14057845 bytes, compressed; MD5 checksum e58f6c51bb796c9c246b957bce85da8d).

2. Install the OOF3D prerequisites, which are listed here. 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.

3. Go to the directory where you want to build OOF3D. We'll assume it's called "oof3d", and is in your home directory:

     cd ~/oof3d
   

4. 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.4.tar.gz
   

   Adjust the directory name as necessary.

   You should now have a directory called oof3d-3.2.4 containing the oof3d source code, installation scripts, and tests.

5. Go the the new oof3d source directory and read the README file.

     cd oof3d-3.2.4
     more README
   

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

   Please note!

   • 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 with sudo, 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 --cocoa to the build command:

       python setup.py build --3D --cocoa

     This will only work if all of the prerequisites have also been built for Quartz/Cocoa. (We have been having difficulty get VTK to work with X11, so building OOF3D and VTK with Cocoa is recommended.)

7. 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 to [email protected]. Tell us exactly what you did, and what went wrong, including all error messages.

8. 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 run.

OOF3D works basically the same way as OOF2, so you can learn a lot about how to use OOF3D by reading the OOF2 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.

• Installation

  --3D must be added to the build and install commands.

  OOF3D includes its own copy of swig, so it's no longer necessary to either install it or to use the --skip-swig flag.

• Image Data

  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 after.)

  You can load an image at start-up by invoking oof3d like this:

    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 mouse button.

  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 Material, etc.

• Microstructures

  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

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

  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 z=0.

  As of version 3.2.0, the Skeleton selection methods have an "operator" parameter, like the Voxel selection methods do.

• Meshes, etc.

  Fields can't be marked "in-plane", and there are no in-plane constraint equations.

• Outputs

  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.

• Automatic skeleton generation is not yet implemented.

• Periodic boundary conditions are not yet implemented.

• 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 3D.

Please report problems to [email protected]. 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:

1. Your operating system and version number.
2. The OOF3D version number.
3. A description of the problem, including what you were doing when the problem occurred, as exactly as possible.
4. Anything that will help us reproduce the problem. This includes:
   • 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 you used.

Known Bugs

• 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 TEST3D/GUI/README file.

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

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 [email protected].

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 THE SOFTWARE.

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.