fixed bugs in "combine_mrc" and the "-normals-file" argument, and added the "-undefined-out" argument

Several changes that probably won't have a big impact on most users.

• Fixed a bug in "combine_mrc" causing thresholding to fail (which was breaking the NAND and NOR examples).
• Fixed a bug so that the "-normals-file" argument (in "filter_mrc") now works better with masks.
• Simplified and generalized the API for "Watershed()" and "ClusterConnected()" (in "segmentation.hpp" and "clustering.hpp").
• Added an "aaaiMarkers" argument to Watershed() (so that it now matches all the features in the scikit-image version). (This feature is not yet available in the "filter_mrc" program.)
• Added the "-undefined-out" argument to "filter_mrc".

bug fix: no longer segfaults when detecting surfaces near image boundaries

This bug was due to failing to check the boundaries of the image when looking up voxel properties. It only occurred when the detected objects were close to the image boundaries. This bug has been fixed.

NOTE: After submitting this release, I noticed that I forgot to also check that the detected voxel coordinates lie within the image mask (if applicable). I'll submit another commit after this to address this issue with masks. (Because its a smaller issue that does not effect as many users, I might not bother to create a new release.)

membrane surfaces now work better with voxellize_mesh.py

Until now, voxellize_mesh.py often was unable to work with meshes generated by the filter_mrc and PoissonRecon programs. In the past, the meshes generated this way often had issues. Topological problems in a mesh can make it difficult for the voxellize_mesh.py program to figure out which voxels lie inside and outside the closed surface, making segmentation of these membrane compartments difficult or impossible.

This update to the code makes the point clouds generated by filter_mrc smoother. This makes PoissonRecon more likely to produce smoother less problematic surfaces. This reduces the probability that the resulting closed surfaces will have with topological problems. I admit that after this change, topological problems are still possible, but it seems to be much less likely now. Once I figure out a more general way to fix these kinds of mesh problems (using meshlab or other 3rd party tools), I'll update the documentation (and the tutorial I'm slowly working on) to help people avoid these kinds of problems. (For now, hopefully the changes in v0.29.8 will really help address this.)

slightly more robust surface edges

This change results in slightly smoother surface reconstructions (when Screened Poisson Reconstruction is used). This commit includes the feature suggested in issue #11.

Assessment of results

Unfortunately, the oriented point-clouds generated by "filter_mrc" do not look noticeably better after this change. (...when viewed visually in meshlab. See the comment in issue #11, for why.) However the number of points on the surface and the length of their surface normals have been adjusted and normalized in this new version of the code. (This is not obvious if you only look at the point cloud in mesh lab.) As a result, if closed-surface reconstruction (a.k.a. "Screened Poisson Reconstruction", "PoissonRecon") is applied to this new point cloud, there will be a modest but somewhat noticeable reduction in bumpiness in the resulting closed surface near the old surface edges.
(Note-to-self: Further improvements might be possible. See my comment in issue #11, which outlines how one might proceed.)

"-dilation-gauss" and "-erosion-gauss" should be working now

Bug fix. The dilation and erosion filters have been working correctly for over a week. But the command-line arguments "-dilation-gauss" and "-erosion-gauss" were not being parsed correctly, so the correct code was not being invoked. (And last week, when I tested it, I misspelled the names of these arguments, so I did not notice the problem. Amazingly, the two errors cancelled out.) Hopefully these filters are working and are behaving consistently with the documentation now.

fixed a bug in dilation and erosion and added soft filters

Since the last release, I fixed a bug in dilation and erosion filtering that was shifting the brightness values downwards by 1. This meant that a binary image (ie. an image with voxel brightnesses of either 0 or 1) that was processed with either dilation or erosion filters would end up as a new image with voxel brightnesses of either -1 or 0. After this fix, the new voxel brightnesses should be between 0 and 1 again.

I also added "soft" versions of the dilation and erosion filters. You can access them from within filter_mrc using the -dilation-binary-soft and -erosion-binary-soft arguments. These only really work well on binary images (whose voxel brightnesses are either 0 or 1).

fixed a bug generating PLY (mesh) files at the wrong magnification

Now the coordinates in the PLY files are scaled by the voxel width so that they have inits of physical distance (instead of voxels). This was the behavior in earlier versions of VISFD before I introduced the bug. This fix should restore that behavior.

auto binning, smoother membranes, better -save-progress

This is a big update.
Many features were added, and changes were made:

• Binning (resolution reduction) is now automatically enabled whenever the features you are trying to detect are larger than ~4.3 voxels wide. (This change was made to address the problem of high-resolution images. As more and more Cryo-EM tomograms are generated with sub-1nm voxel widths, this is a huge problem because the tensor-voting algorithm scales horribly with image resolution.) This should practically have no effect on the accuracy of the detector. Nevertheless, the auto-binning can be disabled using the "-bin 1" argument. (And a warning message is printed to the terminal informing users how to disable auto-binning.) Auto-binning is also enabled when using a blob-detection algorithm to search for blobs that are much larger than 1 voxel wide.
• The "-surface" argument has been renamed to "-membrane". ("-edge" detection also generates surfaces, so I wanted to generalize the notion of what a surface is to include both ridges and edges.)
• When creating PLY files containing surface mesh geometry, the coordinates are now projected onto the actual surface (with sub-voxel accuracy). Voxels which are more than 1 voxel away from this surface (actually sqrt(3)/2 voxels away) are ignored by default. (This can be overridden using the "-max-distance-to-feature" argument.) This will have a big effect on the quality of the surfaces generated.
• When using "-load-progress", you no longer have to re-specify all of the arguments.

overhauled memory allocation and fixed several memory bugs

I rewrote the functions that allocate and free multidimensional arrays (in "alloc2d.hpp" and "alloc3d.hpp"). This simplifies API, shortening the argument list of some of the functions in the VISFD library. These functions are used throughout the code, and this forced me to revisit all of the places in the code where memory was allocated. In the process, I noticed and fixed some memory allocation errors that had crept in. The "filter_mrc" program now passes all valgrind checks when run on the tests in the tests/ directory. I also added move constructors for the "MrcSimple" and "CompactMultiChannelImage3D" classes. (Hopefully all of the classes in the VISFD code now obey the rule of the big five.)

(I also added some very minor features to "morphology.hpp" (the "top hat" transformations), but they are not yet accessible from the filter_mrc program.)

fixed a bug in morphological filters when voxel width≠1

This corrects the behavior of the "-dilation", "-erosion", "-opening", and "-closing" arguments to filter_mrc.

I forgot to take the voxel width into consideration when using morphological filters in filter_mrc. The thickness (width) parameter of the morphological filters was always being interpreted in units of voxels (instead of physical distance, as most other parameters are). Hopefully now this has been corrected. (You can still specify these thickness parameters in voxels, if you prefer that, by using the "-w 1" argument.)