DOC: Detailed descriptions for several filter's parameters (#797)

Signed-off-by: Michael Jackson <[email protected]>

src/Plugins/ComplexCore/docs/CropImageGeometry.md

@@ -2,23 +2,31 @@
 
 ## Description
 
-This **Filter** allows the user to crop an **Image Geometry** of interest.  The input parameters are in units of **Cells**.  For example, if a **Image Geometry** was 100x100x100 **Cells** and each **Cell** was 0.25 x 0.25 x 0.25 units of resolution, then if the user wanted to crop the last 5 microns in the X direction, then the user would enter the following:
+This **Filter** allows the user to crop a region of interest (ROI) from an **Image Geometry**.  The input parameters are in units of voxels.  For example, if a **Image Geometry** has dimensions of 100x100x100 voxels and each voxel was 0.25 x 0.25 x 0.25 units per voxel, then if the user wanted to crop the last 5 microns in the X direction, then the user would enter the following:
 
-Xmin = 80,
-Xmax = 99,
-Ymin = 0,
-Ymax = 99,
-Zmin = 0,
-Zmax = 99
+Bounds: 100 voxels * 0.25 micron/voxel = 25 microns
+
+    Xmin = 80 (20 micron),
+    Xmax = 99 (25 micro),
+    Ymin = 0 (0 micron),
+    Ymax = 99 (25 micron),
+    Zmin = 0 (0 micron),
+    Zmax = 99 (25 micron)
 
 *Note:* The input parameters are *inclusive* and begin at *0*, so in the above example *0-99* covers the entire range of **Cells** in a given dimension.
 
+## Global Position of Cropped Region
+
+Figure 1 shows the position of the cropped region relative to the original image.
+
+![Figure 1](Images/CropImageGeometry_1.png)
+
+## Renumber Features
+
 It is possible with this **Filter** to fully remove **Features** from the volume, possibly resulting in consistency errors if more **Filters** process the data in the pipeline. If the user selects to *Renumber Features* then the *Feature Ids* array will be adjusted so that all **Features** are continuously numbered starting from 1. The user should decide if they would like their **Features** renumbered or left alone (in the case where the cropped output is being compared to some larger volume).
 
 The user has the option to save the cropped volume as a new **Data Container** or overwrite the current volume.
 
-Normally this **Filter** will leave the origin of the volume set at (0, 0, 0), which means output files like the Xdmf file will have the same (0, 0, 0) origin. When viewing both the original larger volume and the new cropped volume simultaneously the cropped volume and the original volume will have the same origin which makes the cropped volume look like it was shifted in space. In order to keep the cropped volume at the same absolute position in space the user should turn **ON** the *Update Origin* check box.
-
 % Auto generated parameter table will be inserted here
 
 ## Example Pipelines

src/Plugins/ComplexCore/src/ComplexCore/Filters/Algorithms/RemoveFlaggedFeatures.cpp

@@ -210,7 +210,6 @@ class RunCropImageGeometryImpl
 
     Arguments args;
 
-    args.insertOrAssign(CropImageGeometry::k_UpdateOrigin_Key, std::make_any<bool>(true));
     args.insertOrAssign(CropImageGeometry::k_RemoveOriginalGeometry_Key, std::make_any<bool>(false));
     args.insertOrAssign(CropImageGeometry::k_SelectedImageGeometry_Key, std::make_any<DataPath>(m_ImageGeometryPath));
     args.insertOrAssign(CropImageGeometry::k_RenumberFeatures_Key, std::make_any<bool>(false));

src/Plugins/ComplexCore/src/ComplexCore/Filters/AppendImageGeometryZSliceFilter.cpp

@@ -249,7 +249,7 @@ IFilter::PreflightResult AppendImageGeometryZSliceFilter::preflightImpl(const Da
   {
     resultOutputActions.warnings().push_back(
         {-8412, "You are appending cell data together which may change the number of features. As a result, any feature level attribute matrix data will likely be invalidated!"});
-    preflightUpdatedValues.push_back({"Appended Image Geometry Info", GeometryHelpers::Description::GenerateGeometryInfo(newDims, spacing, origin)});
+    preflightUpdatedValues.push_back({"Appended Image Geometry Info", GeometryHelpers::Description::GenerateGeometryInfo(newDims, spacing, origin, inputGeometry.getUnits())});
   }
 
   return {std::move(resultOutputActions), std::move(preflightUpdatedValues)};

src/Plugins/ComplexCore/src/ComplexCore/Filters/ApplyTransformationToGeometryFilter.cpp

@@ -356,17 +356,18 @@ IFilter::PreflightResult ApplyTransformationToGeometryFilter::preflightImpl(cons
         // These values should have been updated during the preflightImpl(...) method
         const auto* srcImageGeomPtr = dataStructure.getDataAs<ImageGeom>(srcImagePath);
 
-        preflightUpdatedValues.push_back(
-            {"Input Geometry Info", complex::GeometryHelpers::Description::GenerateGeometryInfo(srcImageGeomPtr->getDimensions(), srcImageGeomPtr->getSpacing(), srcImageGeomPtr->getOrigin())});
+        preflightUpdatedValues.push_back({"Input Geometry Info", complex::GeometryHelpers::Description::GenerateGeometryInfo(srcImageGeomPtr->getDimensions(), srcImageGeomPtr->getSpacing(),
+                                                                                                                             srcImageGeomPtr->getOrigin(), srcImageGeomPtr->getUnits())});
 
         if(pTransformationMatrixTypeValue == k_PrecomputedTransformationMatrixIdx)
         {
           preflightUpdatedValues.push_back({"Transformed Image Geometry Info", K_UNKNOWN_PRECOMPUTED_MATRIX_STR});
         }
         else
         {
-          preflightUpdatedValues.push_back({"Transformed Image Geometry Info",
-                                            complex::GeometryHelpers::Description::GenerateGeometryInfo(dims, CreateImageGeometryAction::SpacingType{spacing[0], spacing[1], spacing[2]}, origin)});
+          preflightUpdatedValues.push_back(
+              {"Transformed Image Geometry Info",
+               complex::GeometryHelpers::Description::GenerateGeometryInfo(dims, CreateImageGeometryAction::SpacingType{spacing[0], spacing[1], spacing[2]}, origin, srcImageGeomPtr->getUnits())});
         }
       }
 

src/Plugins/ComplexCore/src/ComplexCore/Filters/CropImageGeometry.cpp

@@ -159,11 +159,12 @@ Parameters CropImageGeometry::parameters() const
                                                         std::vector<std::string>{"X (Column)", "Y (Row)", "Z (Plane)"}));
   params.insert(std::make_unique<VectorUInt64Parameter>(k_MaxVoxel_Key, "Max Voxel [Inclusive]", "Upper bound of the volume to crop out", std::vector<uint64>{0, 0, 0},
                                                         std::vector<std::string>{"X (Column)", "Y (Row)", "Z (Plane)"}));
-  params.insert(std::make_unique<BoolParameter>(k_UpdateOrigin_Key, "Update Origin", "Specifies if the origin should be updated", false));
+  // params.insert(std::make_unique<BoolParameter>(k_UpdateOrigin_Key, "Update Origin", "Specifies if the origin should be updated", false));
   params.insertLinkableParameter(std::make_unique<BoolParameter>(k_RemoveOriginalGeometry_Key, "Perform In Place", "Removes the original Image Geometry after filter is completed", true));
 
   params.insertSeparator({"Input Geometry and Data"});
-  params.insert(std::make_unique<GeometrySelectionParameter>(k_SelectedImageGeometry_Key, "Selected Image Geometry", "DataPath to the target ImageGeom", DataPath(), std::set{IGeometry::Type::Image}));
+  params.insert(
+      std::make_unique<GeometrySelectionParameter>(k_SelectedImageGeometry_Key, "Selected Image Geometry", "DataPath to the source Image Geometry", DataPath(), std::set{IGeometry::Type::Image}));
 
   params.insertSeparator(Parameters::Separator{"Renumber Features Input Parameters"});
   params.insertLinkableParameter(std::make_unique<BoolParameter>(k_RenumberFeatures_Key, "Renumber Features", "Specifies if the feature IDs should be renumbered", false));
@@ -173,7 +174,7 @@ Parameters CropImageGeometry::parameters() const
       std::make_unique<AttributeMatrixSelectionParameter>(k_FeatureAttributeMatrix_Key, "Cell Feature Attribute Matrix", "DataPath to the feature Attribute Matrix", DataPath({"CellFeatureData"})));
 
   params.insertSeparator({"Output Image Geometry"});
-  params.insert(std::make_unique<DataGroupCreationParameter>(k_CreatedImageGeometry_Key, "Created Image Geometry", "The location of the cropped geometry", DataPath()));
+  params.insert(std::make_unique<DataGroupCreationParameter>(k_CreatedImageGeometry_Key, "Created Image Geometry", "The DataPath to store the created Image Geometry", DataPath()));
 
   // Associate the Linkable Parameter(s) to the children parameters that they control
   params.linkParameters(k_RenumberFeatures_Key, k_CellFeatureIdsArrayPath_Key, true);
@@ -196,7 +197,7 @@ IFilter::PreflightResult CropImageGeometry::preflightImpl(const DataStructure& d
   auto featureIdsArrayPath = filterArgs.value<DataPath>(k_CellFeatureIdsArrayPath_Key);
   auto minVoxels = filterArgs.value<std::vector<uint64>>(k_MinVoxel_Key);
   auto maxVoxels = filterArgs.value<std::vector<uint64>>(k_MaxVoxel_Key);
-  auto shouldUpdateOrigin = filterArgs.value<bool>(k_UpdateOrigin_Key);
+  // auto shouldUpdateOrigin = true; // filterArgs.value<bool>(k_UpdateOrigin_Key);
   auto shouldRenumberFeatures = filterArgs.value<bool>(k_RenumberFeatures_Key);
   auto cellFeatureAmPath = filterArgs.value<DataPath>(k_FeatureAttributeMatrix_Key);
   auto pRemoveOriginalGeometry = filterArgs.value<bool>(k_RemoveOriginalGeometry_Key);
@@ -270,18 +271,9 @@ IFilter::PreflightResult CropImageGeometry::preflightImpl(const DataStructure& d
   std::vector<usize> dataArrayShape = {geomDims[2], geomDims[1], geomDims[0]}; // The DataArray shape goes slowest to fastest (ZYX)
 
   std::vector<float32> targetOrigin(3);
-  if(shouldUpdateOrigin)
-  {
-    targetOrigin[0] = static_cast<float>(xMin) * spacing[0] + srcOrigin[0];
-    targetOrigin[1] = static_cast<float>(yMin) * spacing[1] + srcOrigin[1];
-    targetOrigin[2] = static_cast<float>(zMin) * spacing[2] + srcOrigin[2];
-  }
-  else
-  {
-    targetOrigin[0] = srcOrigin[0];
-    targetOrigin[1] = srcOrigin[1];
-    targetOrigin[2] = srcOrigin[2];
-  }
+  targetOrigin[0] = static_cast<float>(xMin) * spacing[0] + srcOrigin[0];
+  targetOrigin[1] = static_cast<float>(yMin) * spacing[1] + srcOrigin[1];
+  targetOrigin[2] = static_cast<float>(zMin) * spacing[2] + srcOrigin[2];
 
   std::vector<DataPath> ignorePaths; // already copied over so skip these when collecting child paths to finish copying over later
 
@@ -333,10 +325,11 @@ IFilter::PreflightResult CropImageGeometry::preflightImpl(const DataStructure& d
     }
 
     // Store the preflight updated value(s) into the preflightUpdatedValues vector using the appropriate methods.
+    preflightUpdatedValues.push_back({"Input Geometry Info", complex::GeometryHelpers::Description::GenerateGeometryInfo(srcImageGeom->getDimensions(), srcImageGeom->getSpacing(),
+                                                                                                                         srcImageGeom->getOrigin(), srcImageGeom->getUnits())});
     preflightUpdatedValues.push_back(
-        {"Input Geometry Info", complex::GeometryHelpers::Description::GenerateGeometryInfo(srcImageGeom->getDimensions(), srcImageGeom->getSpacing(), srcImageGeom->getOrigin())});
-    preflightUpdatedValues.push_back({"Cropped Image Geometry Info",
-                                      complex::GeometryHelpers::Description::GenerateGeometryInfo(geomDims, CreateImageGeometryAction::SpacingType{spacing[0], spacing[1], spacing[2]}, targetOrigin)});
+        {"Cropped Image Geometry Info",
+         complex::GeometryHelpers::Description::GenerateGeometryInfo(geomDims, CreateImageGeometryAction::SpacingType{spacing[0], spacing[1], spacing[2]}, targetOrigin, srcImageGeom->getUnits())});
   }
   // This section covers the option of renumbering the Feature Data where we need to do a
   // similar creation of the Data Arrays based on the arrays in the Source Image Geometry's

src/Plugins/ComplexCore/src/ComplexCore/Filters/CropImageGeometry.hpp

@@ -23,7 +23,7 @@ class COMPLEXCORE_EXPORT CropImageGeometry : public IFilter
   // Parameter Keys
   static inline constexpr StringLiteral k_MinVoxel_Key = "min_voxel";
   static inline constexpr StringLiteral k_MaxVoxel_Key = "max_voxel";
-  static inline constexpr StringLiteral k_UpdateOrigin_Key = "update_origin";
+  // static inline constexpr StringLiteral k_UpdateOrigin_Key = "update_origin";
   static inline constexpr StringLiteral k_SelectedImageGeometry_Key = "selected_image_geometry";
   static inline constexpr StringLiteral k_CreatedImageGeometry_Key = "created_image_geometry";
   static inline constexpr StringLiteral k_RenumberFeatures_Key = "renumber_features";

src/Plugins/ComplexCore/src/ComplexCore/Filters/ResampleImageGeomFilter.cpp

@@ -253,9 +253,9 @@ IFilter::PreflightResult ResampleImageGeomFilter::preflightImpl(const DataStruct
     }
 
     // Store the preflight updated value(s) into the preflightUpdatedValues vector using
-    preflightUpdatedValues.push_back(
-        {"Input Geometry Info", complex::GeometryHelpers::Description::GenerateGeometryInfo(srcImageGeom->getDimensions(), srcImageGeom->getSpacing(), srcImageGeom->getOrigin())});
-    preflightUpdatedValues.push_back({"Resampled Image Geometry Info", complex::GeometryHelpers::Description::GenerateGeometryInfo(geomDims, pSpacingValue, srcOrigin)});
+    preflightUpdatedValues.push_back({"Input Geometry Info", complex::GeometryHelpers::Description::GenerateGeometryInfo(srcImageGeom->getDimensions(), srcImageGeom->getSpacing(),
+                                                                                                                         srcImageGeom->getOrigin(), srcImageGeom->getUnits())});
+    preflightUpdatedValues.push_back({"Resampled Image Geometry Info", complex::GeometryHelpers::Description::GenerateGeometryInfo(geomDims, pSpacingValue, srcOrigin, srcImageGeom->getUnits())});
   }
 
   // This section covers the option of renumbering the Feature Data where we need to do a

src/Plugins/ComplexCore/src/ComplexCore/Filters/RotateSampleRefFrameFilter.cpp

@@ -447,10 +447,10 @@ IFilter::PreflightResult RotateSampleRefFrameFilter::preflightImpl(const DataStr
     // These values should have been updated during the preflightImpl(...) method
     const auto* srcImageGeom = dataStructure.getDataAs<ImageGeom>(srcImagePath);
 
-    preflightUpdatedValues.push_back(
-        {"Input Geometry Info", complex::GeometryHelpers::Description::GenerateGeometryInfo(srcImageGeom->getDimensions(), srcImageGeom->getSpacing(), srcImageGeom->getOrigin())});
-    preflightUpdatedValues.push_back(
-        {"Rotated Image Geometry Info", complex::GeometryHelpers::Description::GenerateGeometryInfo(dims, CreateImageGeometryAction::SpacingType{spacing[0], spacing[1], spacing[2]}, origin)});
+    preflightUpdatedValues.push_back({"Input Geometry Info", complex::GeometryHelpers::Description::GenerateGeometryInfo(srcImageGeom->getDimensions(), srcImageGeom->getSpacing(),
+                                                                                                                         srcImageGeom->getOrigin(), srcImageGeom->getUnits())});
+    preflightUpdatedValues.push_back({"Rotated Image Geometry Info", complex::GeometryHelpers::Description::GenerateGeometryInfo(
+                                                                         dims, CreateImageGeometryAction::SpacingType{spacing[0], spacing[1], spacing[2]}, origin, srcImageGeom->getUnits())});
   }
 
   // copy over the rest of the data

src/Plugins/ComplexCore/src/ComplexCore/Filters/SetImageGeomOriginScalingFilter.cpp

@@ -5,6 +5,7 @@
 #include "complex/Parameters/BoolParameter.hpp"
 #include "complex/Parameters/GeometrySelectionParameter.hpp"
 #include "complex/Parameters/VectorParameter.hpp"
+#include "complex/Utilities/GeometryHelpers.hpp"
 
 #include <fmt/format.h>
 
@@ -40,7 +41,7 @@ std::string SetImageGeomOriginScalingFilter::humanName() const
 //------------------------------------------------------------------------------
 std::vector<std::string> SetImageGeomOriginScalingFilter::defaultTags() const
 {
-  return {className(), "Image Geometry", "Shift", "Spacing", "Mutate"};
+  return {className(), "Image Geometry", "Shift", "Spacing", "Mutate", "Origin"};
 }
 
 //------------------------------------------------------------------------------
@@ -50,11 +51,13 @@ Parameters SetImageGeomOriginScalingFilter::parameters() const
 
   params.insertSeparator(Parameters::Separator{"Input Parameters"});
   params.insert(std::make_unique<GeometrySelectionParameter>(k_ImageGeomPath_Key, "Image Geometry", "Path to the target ImageGeom", DataPath(), std::set{IGeometry::Type::Image}));
-  params.insertLinkableParameter(std::make_unique<BoolParameter>(k_ChangeOrigin_Key, "Change Origin", "Specifies if the origin should be changed", true));
-  params.insert(std::make_unique<VectorFloat64Parameter>(k_Origin_Key, "Origin", "Specifies the new origin values", std::vector<float64>{0, 0, 0}, std::vector<std::string>{"X", "Y", "Z"}));
+  params.insertLinkableParameter(std::make_unique<BoolParameter>(k_ChangeOrigin_Key, "Set Origin", "Specifies if the origin should be changed", true));
+  params.insert(std::make_unique<VectorFloat64Parameter>(k_Origin_Key, "Origin  (Physical Units)", "Specifies the new origin values in physical units.", std::vector<float64>{0.0, 0.0, 0.0},
+                                                         std::vector<std::string>{"X", "Y", "Z"}));
 
-  params.insertLinkableParameter(std::make_unique<BoolParameter>(k_ChangeResolution_Key, "Change Spacing", "Specifies if the spacing should be changed", true));
-  params.insert(std::make_unique<VectorFloat64Parameter>(k_Spacing_Key, "Spacing", "Specifies the new spacing values", std::vector<float64>{1, 1, 1}, std::vector<std::string>{"X", "Y", "Z"}));
+  params.insertLinkableParameter(std::make_unique<BoolParameter>(k_ChangeResolution_Key, "Set Spacing", "Specifies if the spacing should be changed", true));
+  params.insert(std::make_unique<VectorFloat64Parameter>(k_Spacing_Key, "Spacing (Physical Units)", "Specifies the new spacing values in physical units.", std::vector<float64>{1, 1, 1},
+                                                         std::vector<std::string>{"X", "Y", "Z"}));
 
   params.linkParameters(k_ChangeOrigin_Key, k_Origin_Key, std::make_any<bool>(true));
   params.linkParameters(k_ChangeResolution_Key, k_Spacing_Key, std::make_any<bool>(true));
@@ -77,23 +80,39 @@ IFilter::PreflightResult SetImageGeomOriginScalingFilter::preflightImpl(const Da
   auto origin = filterArgs.value<std::vector<float64>>(k_Origin_Key);
   auto spacing = filterArgs.value<std::vector<float64>>(k_Spacing_Key);
 
-  std::optional<FloatVec3> originVec;
-  std::optional<FloatVec3> spacingVec;
+  std::optional<FloatVec3> optOrigin;
+  std::optional<FloatVec3> optSpacing;
+
+  FloatVec3 originVec = FloatVec3(origin[0], origin[1], origin[2]);
+  FloatVec3 spacingVec = FloatVec3(spacing[0], spacing[1], spacing[2]);
+
+  complex::Result<OutputActions> resultOutputActions;
+
+  std::vector<PreflightValue> preflightUpdatedValues;
 
   if(shouldChangeOrigin)
   {
-    originVec = FloatVec3(origin[0], origin[1], origin[2]);
+    optOrigin = originVec;
   }
   if(shouldChangeResolution)
   {
-    spacingVec = FloatVec3(spacing[0], spacing[1], spacing[2]);
+    spacingVec = spacingVec;
   }
 
-  auto action = std::make_unique<UpdateImageGeomAction>(originVec, spacingVec, imageGeomPath);
+  auto action = std::make_unique<UpdateImageGeomAction>(optOrigin, spacingVec, imageGeomPath);
+
+  resultOutputActions.value().appendAction(std::move(action));
+
+  const auto* srcImageGeom = dataStructure.getDataAs<ImageGeom>(imageGeomPath);
+
+  // Store the preflight updated value(s) into the preflightUpdatedValues vector using the appropriate methods.
+  preflightUpdatedValues.push_back({"Input Geometry  [Before Update]", complex::GeometryHelpers::Description::GenerateGeometryInfo(srcImageGeom->getDimensions(), srcImageGeom->getSpacing(),
+                                                                                                                                   srcImageGeom->getOrigin(), srcImageGeom->getUnits())});
+
+  preflightUpdatedValues.push_back(
+      {"Image Geometry [After Update]", complex::GeometryHelpers::Description::GenerateGeometryInfo(srcImageGeom->getDimensions(), spacingVec, originVec, srcImageGeom->getUnits())});
 
-  OutputActions actions;
-  actions.appendAction(std::move(action));
-  return {std::move(actions)};
+  return {std::move(resultOutputActions), std::move(preflightUpdatedValues)};
 }
 
 //------------------------------------------------------------------------------