DOC: Updates to ConvertOrientationFilter documentation

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

CMakeLists.txt

@@ -1029,7 +1029,7 @@ if(SIMPLNX_BUILD_PYTHON)
   add_subdirectory(wrapping/python)
 endif()
 
-option(SIMPLNX_BUILD_DOCS "Enables buildingdocumentation" OFF)
+option(SIMPLNX_BUILD_DOCS "Enables building documentation" OFF)
 
 if(SIMPLNX_BUILD_DOCS)
   add_subdirectory(docs)

docs/CMakeLists.txt

@@ -1,4 +1,10 @@
-option(SIMPLNX_BUILD_SPHINX_DOCS "Use Sphinx to builddocumentation" OFF)
+# ------------------------------------------------------------------------------
+# Building the Developer Documentation using Doxygen is probably not supported
+# and has not been updated since 2021. This is being left in here for historical
+# reasons and incase someone wants to add this capability in the future.
+# ------------------------------------------------------------------------------
+
+option(SIMPLNX_BUILD_SPHINX_DOCS "Use Doxygen to build developer documentation (Not Supported)" OFF)
 
 find_package(Doxygen REQUIRED)
 
@@ -23,7 +29,7 @@ add_custom_command(OUTPUT ${DOXYGEN_INDEX_FILE}
   DEPENDS ${SIMPLNX_HDRS}
   COMMAND Doxygen::doxygen ${DOXYFILE_OUT}
   MAIN_DEPENDENCY ${DOXYFILE_IN} ${DOXYFILE_OUT}
-  COMMENT "Generating ${PROJECT_NAME} docs with Doxygen"
+  COMMENT "Generating ${PROJECT_NAME} developer docs with Doxygen"
   VERBATIM
 )
 
@@ -38,7 +44,7 @@ endif()
 
 add_custom_target(simplnx_doxygen ${doxygen_default} DEPENDS ${DOXYGEN_INDEX_FILE})
 
-option(SIMPLNX_INSTALL_DOXYGEN_DOCS "Enable install forDoxygen docs" OFF)
+option(SIMPLNX_INSTALL_DOXYGEN_DOCS "Enable install for Doxygen docs" OFF)
 
 include(GNUInstallDirs)
 
@@ -81,7 +87,7 @@ if(SIMPLNX_BUILD_SPHINX_DOCS)
 
   add_custom_target(simplnx_sphinx ${sphinx_default} DEPENDS ${SPHINX_INDEX_FILE})
 
-  option(SIMPLNX_INSTALL_SPHINX_DOCS "Enable install forSphinx docs" OFF)
+  option(SIMPLNX_INSTALL_SPHINX_DOCS "Enable install for Sphinx docs" OFF)
   if(SIMPLNX_INSTALL_SPHINX_DOCS)
     install(DIRECTORY ${SPHINX_BUILD}
       DESTINATION ${CMAKE_INSTALL_DOCDIR}

src/Plugins/OrientationAnalysis/docs/ConvertOrientationsFilter.md

@@ -6,20 +6,38 @@ Orientation Analysis (Conversion)
 
 ## Description
 
-This **Filter** generates a new orientation representation (see Data Layout Table below) for each **Element**, given the *Input Orientation Representation* for the **Element**. The following table lists the various orientation representations that are supported. DREAM3D is capable of converting between any representation with some caveats.
+This **Filter** generates a new orientation representation (see Data Layout Table below) 
+for each **Element**, given the *Input Orientation Representation* for the **Element**.
+The following table lists the various orientation representations that are supported. DREAM3D
+is capable of converting between any representation with some caveats. Use the table
+below to determine the underlying enumeration index for each type of Orientation.
+
+| Input/Output Type Index | Orientation Representation |
+|-------------------------|---------------------------|
+| 0                       | EulerAngles                |
+| 1                       | Orientation Matrix         |
+| 2                       | Quaternions                |
+| 3                       | Axis Angle                 |
+| 4                       | Rodrigues Vectors          |
+| 5                       | Homochoric                 |
+| 6                       | Cubochoric                 |
+| 7                       | StereoGraphic              |
+
 
 ### Data Layout
 
-| Orientation Representation | No. of Components | Representation Type | Data Layout |
-|----------------------------|----------|---------------------|-------------|
-| EulerAngles                | 3 | 0 | phi1, Phi, phi2 |
-| Orientation Matrix         | 9 | 1 | Row Major Format |
-| Quaternions                | 4 | 2 | ( \[x, y, z\], w ) |
-| Axis Angle                 | 4 | 3 | ( \[x, y, z\], Angle) |
-| Rodrigues Vectors          | 4 | 4 | *Internally DREAM.3D keeps a 4th component* |
-| Homochoric                 | 3 | 5 | \[x, y, z\] |
-| Cubochoric                 | 3 | 6 | \[x, y, z\] |
-| StereoGraphic              | 3 | 7 | \[x, y, z\] |
+| Orientation Representation | No. of Components  | Data Layout |
+|----------------------------|---------------------|-------------|
+| EulerAngles                | 3 | phi1, Phi, phi2 |
+| Orientation Matrix         | 9 | Row Major Format |
+| Quaternions                | 4 | ( \[x, y, z\], w ) |
+| Axis Angle                 | 4 | ( \[x, y, z\], Angle) |
+| Rodrigues Vectors          | 4 | ( \[x, y, z\], w )* |
+| Homochoric                 | 3 | \[x, y, z\] |
+| Cubochoric                 | 3 | \[x, y, z\] |
+| StereoGraphic              | 3 | \[x, y, z\] |
+
+- * Rodrigues Vector: DREAM3D stores the Rodrigues vector as a normalized vector with the lenth as the last component.
 
 ### Data Range
 
@@ -29,6 +47,13 @@ The valid range for Euler angles is (Degrees):
     + Phi : 0 to 180
     + phi-2: 0 to 360
 
+Rodrigues Vector: Length must be positive and the vector must be normalized.
+Homochoric Vector: Sum of Squares must = 1.0
+Quaternion: Scalar part must be positive and have unit norm
+Axis Angle: Angle must be in the range of 0-Pi.
+Stereographic Vector: Must be unit norm
+Orientation Matrix: Determinant must be +1.0
+
 ### Data Conversion Notes
 
 If the angles fall outside of this range the **original** Euler Input data **WILL BE CHANGED** to ensure they are within this range.

src/Plugins/OrientationAnalysis/src/OrientationAnalysis/Filters/ConvertOrientationsFilter.cpp

@@ -338,9 +338,10 @@ Parameters ConvertOrientationsFilter::parameters() const
   Parameters params;
   // Create the parameter descriptors that are needed for this filter
   params.insertSeparator(Parameters::Separator{"Input Parameter(s)"});
-  params.insert(std::make_unique<ChoicesParameter>(k_InputType_Key, "Input Orientation Type", "Specifies the incoming orientation representation", 0,
+  params.insert(std::make_unique<ChoicesParameter>(k_InputType_Key, "Input Orientation Type", "Specifies the incoming orientation representation enumeration index", 0,
                                                    OrientationConverterType::GetOrientationTypeStrings<ChoicesParameter::Choices>()));
-  params.insert(std::make_unique<ChoicesParameter>(k_OutputType_Key, "Output Orientation Type", "Specifies to which orientation representation to convert the incoming data", 1,
+  params.insert(std::make_unique<ChoicesParameter>(k_OutputType_Key, "Output Orientation Type",
+                                                   "Specifies to which orientation representation to convert the incoming data. Specified as an enumeration index", 1,
                                                    OrientationConverterType::GetOrientationTypeStrings<ChoicesParameter::Choices>()));
   params.insert(std::make_unique<ArraySelectionParameter>(k_InputOrientationArrayPath_Key, "Input Orientations", "The complete path to the incoming orientation representation data array", DataPath{},
                                                           ArraySelectionParameter::AllowedTypes{DataType::float32}));

wrapping/python/docs/source/User_API.rst

@@ -366,13 +366,13 @@ General Parameters
 .. _ChoicesParameter:
 .. py:class:: ChoicesParameter
 
-   This parameter holds a single value from a list of choices in the form of an integer. The filter documentation
+   This parameter holds a zero based 'index' into a list of choices in the form of an integer. The filter documentation
    should have the valid values to chose from. It is represented in the UI through a ComboBox drop down menu.
    It can be initialized with an integer type.
 
 .. code:: python
 
-    a_combo_box_value = 2
+    a_combo_box_index = 2
 
 .. _DataGroupCreationParameter:
 .. py:class:: DataGroupCreationParameter