DOC: Prepare release notes for SIMPLNX 1.2.7 (#907)

Signed-off-by: Michael Jackson <mike.jackson@bluequartz.net> Signed-off-by: Joey Kleingers <joey.kleingers@bluequartz.net> Co-authored-by: Joey Kleingers <joey.kleingers@bluequartz.net>
BlueQuartzSoftware · Apr 8, 2024 · 4e159ab · 4e159ab
1 parent d1b4b50
commit 4e159ab
Show file tree

Hide file tree

Showing 12 changed files with 142 additions and 56 deletions.
diff --git a/wrapping/python/docs/generate_sphinx_docs.cpp b/wrapping/python/docs/generate_sphinx_docs.cpp
@@ -795,8 +795,8 @@ void GeneratePythonRstFiles()
         rstStream << ", ";
 
         rstStream << parameterPair.first;
-        memberStream << "      :param " << nx::core::StringUtilities::replace(s_ParameterMap[anyParameter->uuid()], "simplnx.", "") << " " << anyParameter->name() << ": " << anyParameter->helpText()
-                     << "\n";
+        memberStream << "      :param nx." << nx::core::StringUtilities::replace(s_ParameterMap[anyParameter->uuid()], "simplnx.", "") << " " << anyParameter->name() << ": "
+                     << anyParameter->helpText() << "\n";
         index++;
       }
       rstStream << ")\n\n";

diff --git a/wrapping/python/docs/index_template.rst b/wrapping/python/docs/index_template.rst
@@ -2,25 +2,45 @@
    compiling additional plugins, and you want the python docs
    generated, you will need to add those to the list below
 
-DREAM3D-NX Python Docs
-=======================
-
-Latest Version: 1.2.7
----------------------
+DREAM3D-NX Python Docs (v1.2.7)
+=================================
 
+Installation
+----------------------
+
 The *simplnx* library can be installed through an Anaconda packages from the *BlueQuartzSoftware* channel. This can be achieved
-by creating a new virtual environment
+by creating a new virtual environment and installing the `dream3dnx` python package.
 
 .. code:: shell
 
     conda config --add channels conda-forge
     conda config --set channel_priority strict
-    conda create -n nxpython python=3.10
+    conda create -n nxpython python=3.12
     conda activate nxpython
-    conda install -c bluequartzsoftware simplnx
+    conda install -c bluequartzsoftware dream3dnx
+
+
+How to use SIMPLNX from Python
+------------------------------
+
+.. attention::
+
+   All users should start with the :ref:`SIMPLNX Python Introduction<SIMPLNXPythonIntroduction>`
+
+
+.. attention::
+
+   Users wanting to integrate the functionality included with SIMPLNX/DREAM3D-NX from within Python, you should 
+   use the link to :ref:`SIMPLNX User API Docs <UserAPIDocs>`
+
+
+.. attention::
+
+   Users wanting to extend DREAM3D-NX by writing filters in the python language should go to the :ref:`Writing a Python Filter <WritingPythonFilters>`
+
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 2
    :caption: Conceptual
 
    Installation
@@ -29,37 +49,37 @@ by creating a new virtual environment
    Geometry
 
 .. toctree::
-   :maxdepth: 3
-   :caption: Using SIMPLNX
+   :maxdepth: 2
+   :caption: Using SIMPLNX in Python
 
    Python_Introduction
    User_API
    Reference_Frame_Notes
 
 .. toctree::
-   :maxdepth: 3
-   :caption: Filter Writers
+   :maxdepth: 1
+   :caption: SIMPLNX Filter Docs
 
-   Writing_A_New_Python_Filter
-   Developer_API
+@PLUGIN_LIST@
 
 .. toctree::
-   :maxdepth: 1
-   :caption: Filter API/Docs
+   :maxdepth: 2
+   :caption: SIMPLNX Filter Writing API
 
-@PLUGIN_LIST@
+   Writing_A_New_Python_Filter
+   Developer_API
 
 .. toctree::
    :maxdepth: 1
    :caption: Release Notes
 
-   ReleaseNotes_110
-   ReleaseNotes_120
-   ReleaseNotes_121
-   ReleaseNotes_123
-   ReleaseNotes_124
-   ReleaseNotes_126
    ReleaseNotes_127
+   ReleaseNotes_126
+   ReleaseNotes_124
+   ReleaseNotes_123
+   ReleaseNotes_121
+   ReleaseNotes_120
+   ReleaseNotes_110
 
 Indices and tables
 ==================

diff --git a/wrapping/python/docs/source/Geometry.rst b/wrapping/python/docs/source/Geometry.rst
@@ -131,7 +131,20 @@ Node Based Geometries (Unstructured Grid)
 These are geometries that consist of an array of vertices (points) where each vertex is
 defined by a vector of 3 x 32 bit floating point values representing the X, Y, and Z value for that point. Each vertex could be shared by 0 or more higher order elements.
 The higher dimensional node geometries will also include a second array that defines the topology or connectivity of
-each element (edge, triangle, ...) for that geometry.
+each element (edge, triangle, ...) for that geometry. There are specific API functions that you can use to resize the Nodes/Edges/Faces/Cells of each
+node based geometry.
+
+.. code:: python
+
+   # Example, this will get a reference to the Edge Geometry
+   edge_geom: nx.EdgeGeom = data_structure[output_edge_geom_path]
+   # Now resize the edge geometry to have 30 Edges
+   edge_geom.resize_edges(30)
+   # Now resize the vertices to have 31 vertices
+   edge_geom.resize_vertices(31)
+   # Both of the resize operations will also resize any attribute matrix that is associated with the vertices and edges.
+
+
 
 VertexGeometry
 ^^^^^^^^^^^^^^^^

diff --git a/wrapping/python/docs/source/Images/AttributeMatrix_Relationship.png b/wrapping/python/docs/source/Images/AttributeMatrix_Relationship.png
diff --git a/wrapping/python/docs/source/Overview.rst b/wrapping/python/docs/source/Overview.rst
@@ -57,7 +57,6 @@ which is the smallest building block of the geometry. **Elements** can have 4 di
 Data attributes can be associated with any of these element types, as long as that association makes sense for the given element topology. For example, a triangulated surface mesh can have **Vertex**, **Edge**, and **Face** data associated with it, but not **Cell** data, since a triangle has a 2-dimensional topology. To help the user keep track of the **Geometry** type associated with a particular **Data Container**, DREAM3D-NX sets default names of **Data Containers** to be prefixed with the **Geometry** type when applicable. For example, a **Data Container** containing an **Image Geometry** would have a default name **ImageDataContainer**. Of course, you can rename **Data Containers** if you prefer a different data scheme.
 
 Currently Implemented Geometries
-
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 +-------------+----------+------------------+---------------------------------------------------------------------------------------------------------------------------------------+
@@ -157,6 +156,15 @@ scales, allowing for connections and correlations to be assessed.
 
 --------------
 
+.. figure:: Images/AttributeMatrix_Relationship.png
+   :scale: 50%
+   :alt: AttributeMatrix_Relationship
+   :align: left
+   :target: path
+
+   Mapping between AttributeMatrix using **Cell Data** "FeatureIds" to link to the feature data and **Cell Data** "Phases" to link to the Ensemble Data
+--------------
+
 .. figure:: Images/Elements_Features_Ensembles.png
    :alt: Object-Attribute Associations
 

diff --git a/wrapping/python/docs/source/Python_Introduction.rst b/wrapping/python/docs/source/Python_Introduction.rst
@@ -1,3 +1,5 @@
+.. _SIMPLNXPythonIntroduction:
+
 Python Example Usage
 ====================
 

diff --git a/wrapping/python/docs/source/Reference_Frame_Notes.md b/wrapping/python/docs/source/Reference_Frame_Notes.md
@@ -22,16 +22,16 @@ DREAM.3D can represent orientations in seven different forms:
 
 In many cases, a direct transformation is available from one representation to another; in some cases, an intermediate representation is used, e.g., from homochoric (h) to Euler (e), DREAM.3D first transforms to an axis angle pair (a), then to an orientation matrix (o), and finally to Euler angles.
 
-| From/To |  e   |  o   |  a   |  r   |  q   |  h   |  c   | s  |
-|  -      |  -   |  -   |  -   |  -   |  -   |  -   |  -   |    |
-|  e      |  -   |  X   |  X   |  X   |  X   |  a   | ah   |    |
-|  o      |  X   |  --  |  X   |  e   |  X   |  a   | ah   |    |
-|  a      |  o   |  X   | --   |  X   |  X   |  X   |  h   |    |
-|  r      |  o   |  a   |  X   | --   |  a   |  X   |  h   |    |
-|  q      |  X   |  X   |  X   |  X   | --   |  X   |  h   |    |
-|  h      |  ao  |  a   |  X   |  a   |  a   | --   |  X   |    |
-|  c      | hao  |  ha  |  h   |  ha  | ha   |  X   | --   |    |
-|  s      |      |      |      |      |      |      |      | -- |
+| From/To |  e   |  o   |  a   |  r   |  q   |  h   |  c   |   s  |
+|---------|------|------|------|------|------|------|------|------|
+|  e      |  --  |  X   |  X   |  X   |  X   |  a   | ah   |      |
+|  o      |  X   |  --  |  X   |  e   |  X   |  a   | ah   |      |
+|  a      |  o   |  X   |  --  |  X   |  X   |  X   |  h   |      |
+|  r      |  o   |  a   |  X   |  --  |  a   |  X   |  h   |      |
+|  q      |  X   |  X   |  X   |  X   |  --  |  X   |  h   |      |
+|  h      |  ao  |  a   |  X   |  a   |  a   |  --  |  X   |      |
+|  c      | hao  |  ha  |  h   |  ha  | ha   |  X   |  --  |      |
+|  s      |      |      |      |      |      |      |      |  --  |
 
 ## Filters to Assist the User
 

diff --git a/wrapping/python/docs/source/ReleaseNotes_127.rst b/wrapping/python/docs/source/ReleaseNotes_127.rst
@@ -16,10 +16,48 @@ API Changes & Additions 1.2.7
 
 - The ColorTableParameter API has changed. Please see either the developer or user documentation for more details.
 - A few filters have changed their name
-- DataPath has had more API take from parts of PathLib. See the documentation for the new API additions
+- DataPath has had more API taken from parts of PathLib. See the documentation for the new API additions.[https://www.dream3d.io/python_docs/DataObjects.html#datapath](https://www.dream3d.io/python_docs/DataObjects.html#datapath)
 - Node based geometries allow the resizing of their internal data structures using the `resize_*` methods.
 
 Change Log 1.2.7
 ^^^^^^^^^^^^^^^^^^^^
 
-
+- PY: Add python bindings to allow Node based geometries to resize correctly (#906) [8b1f2373]
+- Filter: Read VTK Structured Points (#905) [75122bbf]
+- ENH/BUG: Add DataStructure::validateGeometries() and ::validateAttributeMatrices() method (#903) [cab149c6]
+- ENH: Remove the LinkedGeometryData class since it is no longer used. (#908) [888ba21d]
+- ENH: Update error messages from DataArrayIO and StringArrayIO (#901) [d769fce3]
+- DOC: Add example for GeneratedFileListParameter in Python (#902) [7021f182]
+- BUG: Fixed issue with failing print causing filter to fail (#899) [5da9e786]
+- DOC: Update Python documentation with improved navigation (#895) [c59e375c]
+- ENH: GeneratePythonPlugin can generate batch/shell init file. (#896) [8f1a45df]
+- ENH: Misc doc and filter updates for ITK, ExtractInternalSurfaces and SurfaceNets (#898) [d43cc50b]
+- FILTER : ExtractPipelineToFile added (#897) [8b748077]
+- FILTER: Add H5OINAReader (#700) [a51dd5f3]
+- BUG: Small bugs, doc fixes, StopWatch class added (#894) [327e4b65]
+- BUG: StringUtilities::split-Add Additional Edge Case Checks(#893) [3a9c87d8]
+- BUG: Rename GenerateFaceMisorientationColors to GenerateFeatureFaceMisorientations (#889) [5ed1cd93]
+- BUG: Return invalid Result<> if size of directory is requested. (#891) [219471be]
+- BUG/ENH: StringUtilities Split Function Updates (#892) [381aecc4]
+- ENH: Report total installed memory on some memory allocation errors (#887) [0343a96c]
+- ENH : Add support for getting the pipeline json object from a dream3d file (#890) [6a80a1be]
+- ENH: Add checks to ensure vertex cropping bounds are not the same. (#888) [e9f0542a]
+- ENH: Forward error messages when creating Node geometries. (#885) [eed0c9b4]
+- FILT: ITKImageProcessing - Add new batch of filters (#884) [daea37d6]
+- BUG: Fix python plugin generation codes (#881) [60a81213]
+- ENH: Initialize Data - Increased Variance in Random Generation for Floats (#880) [023c9896]
+- BUG: Fix resetting of the DataStructure::Id when importing from a file. (#879) [8e4e8f98]
+- ENH: GeneratePythonFilter-Crashing fixed, Generation Fixed, headers split (#877) [fa92713c]
+- BUG FIX: Find Array Statistics (#878) [1645a22f]
+- ENH: ReadMHAFile-Allow user to transpose stored matrix and other UI improvements (#871) [f9034641]
+- BUG: Fix accepted input file extension types for ConvertHexGridToSquarGridFilter (#875) [eb588250]
+- ENH: Update Generate Color Table Filter and Parameter (#866) [d4264ca1]
+- ENH: CombineSTLFiles-Add option to label the faces and vertices based on a file index (#873) [93ca6a33]
+- PY: Use consistent simplnx alias, tweak parameter declaration sections. (#872) [5340383d]
+- BUG: Fix issue where spacing would be set to 1,1,1 (#870) [c8f5f0cf]
+- FILTER: Rename 'Contouring' to 'FlyingEdges3D' (#869) [b6a50195]
+- PY: DataPath API additions, Example OpenCV filter included. (#868) [1b1d2d8d]
+- PYTHON FILTER: Contour Statistics (#865) [da8428bd]
+- BUG: ReadH5Ebsd-Fix issue creating proper sized Attribute Matrix for Ensemble Data (#863) [c089bc23]
+- DOCS: Implement python developer documentation including filter examples and a tutorial (#837) [2a7b94cd]
+- PY: Add support for Python 3.12 with HDF5 1.14. (#861) [5b24757e]
diff --git a/wrapping/python/docs/source/User_API.rst b/wrapping/python/docs/source/User_API.rst
@@ -1,5 +1,7 @@
-API for Users
-==============
+.. _UserAPIDocs:
+
+SIMPLNX Python API
+===================
 
 Error & Warning Reporting
 --------------------------
@@ -81,17 +83,18 @@ General Parameters
   .. code:: python
 
    threshold_1 = nx.ArrayThreshold()
-   threshold_1.array_path = nx.DataPath(["Small IN100", "Scan Data", "Confidence Index"])
+   threshold_1.array_path = nx.DataPath("Small IN100/Scan Data/Confidence Index")
    threshold_1.comparison = nx.ArrayThreshold.ComparisonType.GreaterThan
    threshold_1.value = 0.1
 
    threshold_2 = nx.ArrayThreshold()
-   threshold_2.array_path = nx.DataPath(["Small IN100", "Scan Data", "Image Quality"])
+   threshold_2.array_path = nx.DataPath("Small IN100/Scan Data/Image Quality")
    threshold_2.comparison = nx.ArrayThreshold.ComparisonType.GreaterThan
    threshold_2.value = 120
 
    threshold_set = nx.ArrayThresholdSet()
    threshold_set.thresholds = [threshold_1, threshold_2]
+   threshold_set.union_op = nx.IArrayThreshold.UnionOperator.And
    result = nx.MultiThresholdObjects.execute(data_structure=data_structure,
                                        array_thresholds=threshold_set, 
                                        created_data_path="Mask",
@@ -104,7 +107,7 @@ General Parameters
 
   .. code:: python
 
-    data_path = nx.DataPath(["Small IN100", "Scan Data"])   
+    data_path = nx.DataPath("Small IN100/Scan Data")
 
 .. _BoolParameter:
 .. py:class:: BoolParameter
@@ -128,11 +131,11 @@ General Parameters
 
 .. code:: python
 
-   selected_group = nx.DataPath(["Small IN100","Scan Data"])
+   selected_group = nx.DataPath("Small IN100/Scan Data")
    infix_equation = "Confidence Index * 10"
    calc_param = nx.CalculatorParameter.ValueType( selected_group, infix_equation, nx.CalculatorParameter.AngleUnits.Radians)
    result = nx.ArrayCalculatorFilter.execute(data_structure = data_structure,
-                                             calculated_array=nx.DataPath(["Small IN100","Scan Data","Calulated CI"]), 
+                                             calculated_array=nx.DataPath("Small IN100/Scan Data/Calulated CI"),
                                              calculator_parameter = calc_param, 
                                              scalar_type=nx.NumericType.float32)
 
@@ -157,7 +160,7 @@ General Parameters
 
   .. code:: python
 
-    data_path = nx.DataPath(["Small IN100", "Scan Data"])
+    data_path = nx.DataPath("Small IN100/Scan Data")
 
 .. _DataGroupSelectionParameter:
 .. py:class:: DataGroupSelectionParameter
@@ -166,7 +169,7 @@ General Parameters
 
   .. code:: python
 
-    data_path = nx.DataPath(["Small IN100", "Scan Data"])
+    data_path = nx.DataPath("Small IN100/Scan Data")
 
 .. _DataObjectNameParameter:
 .. py:class:: DataObjectNameParameter
@@ -184,7 +187,7 @@ General Parameters
 
   .. code:: python
 
-    data_path = nx.DataPath(["Small IN100", "Scan Data", "Confidence Index"])
+    data_path = nx.DataPath("Small IN100/Scan Data/Confidence Index")
 
 .. _DataStoreFormatParameter:
 .. py:class:: DataStoreFormatParameter
@@ -330,7 +333,7 @@ General Parameters
 
       result = nx.GenerateColorTableFilter.execute(data_structure=data_structure,
                                               rgb_array_path="CI Color", 
-                                              selected_data_array_path=nx.DataPath(["Small IN100", "Scan Data", "Confidence Index"]), 
+                                              selected_data_array_path=nx.DataPath("Small IN100/Scan Data/Confidence Index"), 
                                               selected_preset="hsv")      
 
 .. _GeneratedFileListParameter:

diff --git a/wrapping/python/docs/source/Writing_A_New_Python_Filter.rst b/wrapping/python/docs/source/Writing_A_New_Python_Filter.rst
@@ -1,4 +1,6 @@
-Writing a New Python Filter
+.. _WritingPythonFilters:
+
+Writing a Python Filter
 ===========================
 
 0. Environment Setup
@@ -38,7 +40,7 @@ Wait until the environment is fully installed.
 
         .. code:: shell
 
-            $CONDA_PREFIX/bin/DREAM3DNX.app/Contents/MacOS/DREAM3DNX
+            dream3dnx
     
     **Linux**
 
@@ -112,7 +114,7 @@ After you have generated your Python plugin/filters, close the current instance
 
         .. code:: shell
 
-            $CONDA_PREFIX/bin/DREAM3DNX.app/Contents/MacOS/DREAM3DNX
+            dream3dnx
     
     **Linux**
 

diff --git a/wrapping/python/docs/source/conf.py b/wrapping/python/docs/source/conf.py
@@ -6,7 +6,7 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = 'DREAM3D-NX'
+project = 'SIMPLNX Python Docs'
 copyright = '2024, BlueQuartz Software, LLC'
 author = 'BlueQuartz Software, LLC'
 release = '1.2.7'

diff --git a/wrapping/python/examples/scripts/basic_arrays.py b/wrapping/python/examples/scripts/basic_arrays.py
@@ -106,7 +106,7 @@
 
 
 result = nx.CreateDataGroup.execute(data_structure=data_structure, 
-                                    data_object_path=nx.DataPath("/Some/Path/To/Group"));
+                                    data_object_path=nx.DataPath("/Some/Path/To/Group"))
 nxtest.check_filter_result(nx.CreateDataGroup, result)