Module Conversion Steps

This step-by-step guide walks you through conversion of a module from SCIRun 4 to SCIRun 5. At this time, it only covers modules without a UI screen.

Phase 1: Physical file preparation

1. Copy the module's C++ source file into the correct path. Look under src/Modules/Legacy to see if it is already there.

• Example: src/Modules/Legacy/Fields/AlignMeshBoundingBoxes.cc is already checked in, so nothing to do.

2. Make a copy of the file SCIRunGUIPrototype/src/Modules/Legacy/Fields/CalculateGradients.h (TODO: general header template) and rename it using the same name as the module. It will act as a template for the newly-required module header file.

• Example: Copied CalculateGradients.h to AlignMeshBoundingBoxes.h.

3. Edit the corresponding CMakeLists.txt file to both (a) enable/add the module .cc file, and (b) add the newly-created module header file.

• Example: src/Modules/Legacy/Fields/CMakeLists.txt was edited to add AlignMeshBoundingBoxes.h to the Dataflow_Modules_Legacy_Fields_HEADERS list; and, the line containing AlignMeshBoundingBoxes.cc was uncommented to add both files to the project.

4. Under src/Modules/X/Tests, where X is the general category of your module, add a unit test source file both to the filesystem and to the corresponding CMakeLists.txt file.

• Example: Unit tests for the Legacy modules are separated from the Legacy directories to aid file diffing. Thus, a file AlignMeshBoundingBoxesTests.cc was added to src/Modules/Fields/Tests, and then added to the project using CMake. GetFieldBoundaryTests.cc was copied to create the new file; it will be edited in a later step.

5. At this point, the CMake project structure should be valid (although the projects won't build), and your git changeset should look like this:
6. CHECKPOINT: If there is no corresponding Algorithm class for your module, there is a limit on the size of its execute() method of 5 lines. Otherwise, a separate Algorithm class is required to be extracted from the Module's implementation.
7. With the Algorithm implementation separate, proceed to the Algorithm class's directory.

• Example: AlignMeshBoundingBoxes uses AlignMeshBoundingBoxes.h/.cc under src/Core/Algorithms/Legacy/Fields/TransformMesh, the files are already there.

8. Enable/add the algorithm source files to the correct CMake project.

• Example: src/Core/Algorithms/Legacy/Fields/CMakeLists.txt is edited to enable TransformMesh/AlignMeshBoundingBoxes.cc and add TransformMesh/AlignMeshBoundingBoxes.h (Most algorithm header files are not part of the CMakeLists file already and need to be added).

9. Repeat step 4 for the Algorithm code. Everything needs test code.

• Example: The new algorithm tests will go under src/Core/Algorithms/Field/Tests. An existing test file is copied into the new file AlignMeshBoundingBoxesAlgoTests.cc, and it is added to the CMake file.

10. Your CMake config should be valid, and it is time to make a commit. It's good to separate the file additions and CMake changes from actual code changes in the history.

• Example:

Phase 2: Algorithm compilation

11. Regenerate your project files and start a build. Most likely the algorithm class will fail to compile. The steps to get it compiling generally break down like this:
12. Fix/delete unneeded include paths.

• Example:

13. Update namespaces.

• Example:

14. Update the base class for the Algorithm type.

• Example:

15. Move all implementation to the .cc file.

• Example:

16. The Algorithm parameter interfaces are centralized under one set of methods, addParameter/get/set. They don't take raw strings anymore, but need an object defined as a key for each parameter. Use a static member variable for each parameter name.

• Examples:

17. The algo_start/end interface is removed, instead use ScopedAlgorithmStatusReporter.

• Example:

18. Interface changes due switch from LockingHandle to boost::shared_ptr

• Example:

19. Certain functions are not available yet, for now macro out their calls (TODO: this step needs to go away soon).

• Example:

20. asVector() calls need to be removed.

• Example:

21. The interface for deep-copying a field/mesh has changed.

• Example:

22. There is a chance that you encounter a compiler error related to another interface change or utility library code that is not enabled yet. In this case, contact @dcwhite and he will work with you on your branch to enable the code you need.

Phase 3: Algorithm Upgrading and testing

23. Open the algorithm unit test source file created in step 9. Create a dummy test similar to the following:

• TEST(AlignMeshBoundingBoxesAlgoTests, Foo) { AlignMeshBoundingBoxesAlgo algo; FAIL() << "TODO"; }

Phase 4: Module conversion

Phase 4: Factory hook-up

Phase 3: Algorithm Testing

Phase 5: Sanity check