From 6137b7b75f36c52bbaafa335f4f1aa6a33d30ecc Mon Sep 17 00:00:00 2001 From: Michael Jackson Date: Thu, 8 Aug 2024 14:39:38 -0400 Subject: [PATCH] DOC: Updates to python docs (#1039) * DOC: Updates to python docs * Python Plugin updates * Added python release notes --------- Signed-off-by: Michael Jackson --- src/Plugins/SimplnxCore/docs/DBSCANFilter.md | 2 +- .../docs/RemoveFlaggedVerticesFilter.md | 2 +- wrapping/python/docs/index_template.rst | 21 +++---- wrapping/python/docs/source/Installation.rst | 20 ++----- wrapping/python/docs/source/Tutorial_3.rst | 2 +- wrapping/python/docs/source/User_API.rst | 2 +- wrapping/python/docs/source/conf.py | 2 +- .../{ => release_notes}/ReleaseNotes_110.rst | 0 .../{ => release_notes}/ReleaseNotes_120.rst | 0 .../{ => release_notes}/ReleaseNotes_121.rst | 0 .../{ => release_notes}/ReleaseNotes_123.rst | 0 .../{ => release_notes}/ReleaseNotes_124.rst | 0 .../{ => release_notes}/ReleaseNotes_126.rst | 0 .../{ => release_notes}/ReleaseNotes_127.rst | 0 .../{ => release_notes}/ReleaseNotes_130.rst | 0 .../ReleaseNotes_240605.rst | 0 .../release_notes/ReleaseNotes_240803.rst | 57 +++++++++++++++++++ .../NXDataAnalysisToolkit/conda/meta.yaml | 12 ++-- 18 files changed, 85 insertions(+), 35 deletions(-) rename wrapping/python/docs/source/{ => release_notes}/ReleaseNotes_110.rst (100%) rename wrapping/python/docs/source/{ => release_notes}/ReleaseNotes_120.rst (100%) rename wrapping/python/docs/source/{ => release_notes}/ReleaseNotes_121.rst (100%) rename wrapping/python/docs/source/{ => release_notes}/ReleaseNotes_123.rst (100%) rename wrapping/python/docs/source/{ => release_notes}/ReleaseNotes_124.rst (100%) rename wrapping/python/docs/source/{ => release_notes}/ReleaseNotes_126.rst (100%) rename wrapping/python/docs/source/{ => release_notes}/ReleaseNotes_127.rst (100%) rename wrapping/python/docs/source/{ => release_notes}/ReleaseNotes_130.rst (100%) rename wrapping/python/docs/source/{ => release_notes}/ReleaseNotes_240605.rst (100%) create mode 100644 wrapping/python/docs/source/release_notes/ReleaseNotes_240803.rst diff --git a/src/Plugins/SimplnxCore/docs/DBSCANFilter.md b/src/Plugins/SimplnxCore/docs/DBSCANFilter.md index 0ecddaccac..655ab0511a 100644 --- a/src/Plugins/SimplnxCore/docs/DBSCANFilter.md +++ b/src/Plugins/SimplnxCore/docs/DBSCANFilter.md @@ -6,7 +6,7 @@ DREAM3D Review (Clustering) ## Description -This **Filter** applies the DBSCAN (density-based spatial clustering of applications with noise) algorithm to an **Attribute Array**. DBSCAN is a _clustering algorithm_ that assigns to each point of the **Attribute Array** a _cluster Id_; points that have the same cluster Id are grouped together more densely (in the sense that the _distance_ between them is small) in the data space (i.e., points that have many nearest neighbors will belong to the same cluster). The user may select from a number of options to use as the distance metric. Points that are in sparse regions of the data space are considered "outliers"; these points will belong to cluster Id 0. Additionally, the user may opt to use a mask to ignore certain points; where the mask is _false_, the points will be categorized as outliers and placed in cluster 0. The algorithm requires two parameters: a _neighborbood region_, called epsilon; and the minimum number of points needed to form a cluster. The algorithm, in pseudocode, proceeds as follows: +This **Filter** applies the DBSCAN (density-based spatial clustering of applications with noise) algorithm to an **Attribute Array**. DBSCAN is a *clustering algorithm* that assigns to each point of the **Attribute Array** a *cluster Id*; points that have the same cluster Id are grouped together more densely (in the sense that the _distance_ between them is small) in the data space (i.e., points that have many nearest neighbors will belong to the same cluster). The user may select from a number of options to use as the distance metric. Points that are in sparse regions of the data space are considered "outliers"; these points will belong to cluster Id 0. Additionally, the user may opt to use a mask to ignore certain points; where the mask is *false*, the points will be categorized as outliers and placed in cluster 0. The algorithm requires two parameters: a *neighborbood region*, called epsilon; and the minimum number of points needed to form a cluster. The algorithm, in pseudocode, proceeds as follows: for each point p in dataset { diff --git a/src/Plugins/SimplnxCore/docs/RemoveFlaggedVerticesFilter.md b/src/Plugins/SimplnxCore/docs/RemoveFlaggedVerticesFilter.md index 764e77b387..2f6ccc642c 100644 --- a/src/Plugins/SimplnxCore/docs/RemoveFlaggedVerticesFilter.md +++ b/src/Plugins/SimplnxCore/docs/RemoveFlaggedVerticesFilter.md @@ -6,7 +6,7 @@ Data Cleanup (Geometry) ## Description -This **Filter** removes **Vertices** from the supplied **Vertex Geometry** that are flagged as **TRUE** by a boolean mask array. A new reduced **Vertex Geometry** is created that contains all the remaining **Vertices**. It is unknown until run time how many **Vertices** will be removed from the **Geometry**. Therefore, this **Filter** requires that a new **Data Container** be created to contain the reduced **Vertex Geometry**. This new **Vertex Geometry** will contain copies of any **Feature** or **Ensemble** **Attribute Matrices** from the original **Data Container**. Additionally, _all **Vertex** data will be copied_, with tuples *removed* for any **Vertices** removed by the **Filter**. The user must supply a name for the reduced **Vertex Geometry**, but all other copied objects (**Attribute Matrices** and **Attribute Arrays**) will retain the same names as the original source. +This **Filter** removes **Vertices** from the supplied **Vertex Geometry** that are flagged as **TRUE** by a boolean mask array. A new reduced **Vertex Geometry** is created that contains all the remaining **Vertices**. It is unknown until run time how many **Vertices** will be removed from the **Geometry**. Therefore, this **Filter** requires that a new **Data Container** be created to contain the reduced **Vertex Geometry**. This new **Vertex Geometry** will contain copies of any **Feature** or **Ensemble** **Attribute Matrices** from the original **Data Container**. Additionally, *all **Vertex** data will be copied*, with tuples *removed* for any **Vertices** removed by the **Filter**. The user must supply a name for the reduced **Vertex Geometry**, but all other copied objects (**Attribute Matrices** and **Attribute Arrays**) will retain the same names as the original source. *Note:* Since it cannot be known before run time how many **Vertices** will be removed, the new **Vertex Geometry** and all associated **Vertex** data to be copied will be initialized to have size 0. Any **Feature** or **Ensemble** information will retain the same dimensions and size. diff --git a/wrapping/python/docs/index_template.rst b/wrapping/python/docs/index_template.rst index 44c79fdddc..7d6ceb8314 100644 --- a/wrapping/python/docs/index_template.rst +++ b/wrapping/python/docs/index_template.rst @@ -2,7 +2,7 @@ compiling additional plugins, and you want the python docs generated, you will need to add those to the list below -DREAM3D-NX Python Docs (v24.06.05) +DREAM3D-NX Python Docs (v24.08.03) =================================== Installation @@ -85,15 +85,16 @@ How to use SIMPLNX from Python :maxdepth: 1 :caption: Release Notes - ReleaseNotes_240605 - ReleaseNotes_130 - ReleaseNotes_127 - ReleaseNotes_126 - ReleaseNotes_124 - ReleaseNotes_123 - ReleaseNotes_121 - ReleaseNotes_120 - ReleaseNotes_110 + release_notes/ReleaseNotes_240803 + release_notes/ReleaseNotes_240605 + release_notes/ReleaseNotes_130 + release_notes/ReleaseNotes_127 + release_notes/ReleaseNotes_126 + release_notes/ReleaseNotes_124 + release_notes/ReleaseNotes_123 + release_notes/ReleaseNotes_121 + release_notes/ReleaseNotes_120 + release_notes/ReleaseNotes_110 Indices and tables ================== diff --git a/wrapping/python/docs/source/Installation.rst b/wrapping/python/docs/source/Installation.rst index ad0a36c5a1..5331db3e0b 100644 --- a/wrapping/python/docs/source/Installation.rst +++ b/wrapping/python/docs/source/Installation.rst @@ -1,28 +1,17 @@ Installation ============ -Latest Version: 24.06.05 +Latest Version: 24.08.03 ------------------------- The *simplnx* library can be installed through an Anaconda packages from the *BlueQuartzSoftware* channel. This can be achieved by creating a new virtual environment and installing SIMPLNX into that environment. -SIMPLNX Installation -^^^^^^^^^^^^^^^^^^^^ - .. attention:: - This kind of installation will allow you to utilize the SIMPLNX library through python. - -.. code:: shell - - conda config --add channels conda-forge - conda config --set channel_priority strict - conda create -n nxpython python=3.10 - conda activate nxpython - conda install -c bluequartzsoftware simplnx - + Intel based MacOS machines can *ONLY* install up to Python 3.11. Due to dependecies from + conda-forge, Python 3.12 is not possible as of AUG 2024. Full DREAM3D-NX Installation @@ -36,7 +25,6 @@ Full DREAM3D-NX Installation 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 dream3dnx - diff --git a/wrapping/python/docs/source/Tutorial_3.rst b/wrapping/python/docs/source/Tutorial_3.rst index 0eea9ebe8d..a095dbb756 100644 --- a/wrapping/python/docs/source/Tutorial_3.rst +++ b/wrapping/python/docs/source/Tutorial_3.rst @@ -35,7 +35,7 @@ When Creating a New Plugin (**Use Existing Plugin** is unchecked) - **Filter Names (comma-separated)**: This field allows you to specify the programmatic names of the filters you want to create. Each filter name should be separated by a comma. For example, `FirstFilter,SecondFilter`. When Using an Existing Plugin (**Use Existing Plugin** is checked) -***************************************************************** +******************************************************************* - **Existing Plugin Location**: This specifies the directory of the existing plugin to which you want to add new filters. You can select the directory by clicking the `Browse` button. diff --git a/wrapping/python/docs/source/User_API.rst b/wrapping/python/docs/source/User_API.rst index 137fd6d570..08dd392566 100644 --- a/wrapping/python/docs/source/User_API.rst +++ b/wrapping/python/docs/source/User_API.rst @@ -36,7 +36,7 @@ Error & Warning Reporting print(f"{filter.name()} :: No errors running the filter") Creating Geometries ------------------- +-------------------- All the `simplnx` geometries can be created in Python using the following helper methods: diff --git a/wrapping/python/docs/source/conf.py b/wrapping/python/docs/source/conf.py index 35a23594dc..b513d8f041 100644 --- a/wrapping/python/docs/source/conf.py +++ b/wrapping/python/docs/source/conf.py @@ -9,7 +9,7 @@ project = 'SIMPLNX Python Docs' copyright = '2024, BlueQuartz Software, LLC' author = 'BlueQuartz Software, LLC' -release = '1.3.0' +release = '24.08.03' # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration diff --git a/wrapping/python/docs/source/ReleaseNotes_110.rst b/wrapping/python/docs/source/release_notes/ReleaseNotes_110.rst similarity index 100% rename from wrapping/python/docs/source/ReleaseNotes_110.rst rename to wrapping/python/docs/source/release_notes/ReleaseNotes_110.rst diff --git a/wrapping/python/docs/source/ReleaseNotes_120.rst b/wrapping/python/docs/source/release_notes/ReleaseNotes_120.rst similarity index 100% rename from wrapping/python/docs/source/ReleaseNotes_120.rst rename to wrapping/python/docs/source/release_notes/ReleaseNotes_120.rst diff --git a/wrapping/python/docs/source/ReleaseNotes_121.rst b/wrapping/python/docs/source/release_notes/ReleaseNotes_121.rst similarity index 100% rename from wrapping/python/docs/source/ReleaseNotes_121.rst rename to wrapping/python/docs/source/release_notes/ReleaseNotes_121.rst diff --git a/wrapping/python/docs/source/ReleaseNotes_123.rst b/wrapping/python/docs/source/release_notes/ReleaseNotes_123.rst similarity index 100% rename from wrapping/python/docs/source/ReleaseNotes_123.rst rename to wrapping/python/docs/source/release_notes/ReleaseNotes_123.rst diff --git a/wrapping/python/docs/source/ReleaseNotes_124.rst b/wrapping/python/docs/source/release_notes/ReleaseNotes_124.rst similarity index 100% rename from wrapping/python/docs/source/ReleaseNotes_124.rst rename to wrapping/python/docs/source/release_notes/ReleaseNotes_124.rst diff --git a/wrapping/python/docs/source/ReleaseNotes_126.rst b/wrapping/python/docs/source/release_notes/ReleaseNotes_126.rst similarity index 100% rename from wrapping/python/docs/source/ReleaseNotes_126.rst rename to wrapping/python/docs/source/release_notes/ReleaseNotes_126.rst diff --git a/wrapping/python/docs/source/ReleaseNotes_127.rst b/wrapping/python/docs/source/release_notes/ReleaseNotes_127.rst similarity index 100% rename from wrapping/python/docs/source/ReleaseNotes_127.rst rename to wrapping/python/docs/source/release_notes/ReleaseNotes_127.rst diff --git a/wrapping/python/docs/source/ReleaseNotes_130.rst b/wrapping/python/docs/source/release_notes/ReleaseNotes_130.rst similarity index 100% rename from wrapping/python/docs/source/ReleaseNotes_130.rst rename to wrapping/python/docs/source/release_notes/ReleaseNotes_130.rst diff --git a/wrapping/python/docs/source/ReleaseNotes_240605.rst b/wrapping/python/docs/source/release_notes/ReleaseNotes_240605.rst similarity index 100% rename from wrapping/python/docs/source/ReleaseNotes_240605.rst rename to wrapping/python/docs/source/release_notes/ReleaseNotes_240605.rst diff --git a/wrapping/python/docs/source/release_notes/ReleaseNotes_240803.rst b/wrapping/python/docs/source/release_notes/ReleaseNotes_240803.rst new file mode 100644 index 0000000000..6b9ae90922 --- /dev/null +++ b/wrapping/python/docs/source/release_notes/ReleaseNotes_240803.rst @@ -0,0 +1,57 @@ +Release Notes 24.08.03 +====================== + +With this release we are moving towards a YYMMDD style of versioning. The `simplnx` library is +under activate development and while we strive to maintain a stable API bugs are +found that necessitate the changing of the API. + +Version 24.08.03 +----------------- + + +API Changes & Additions 24.08.03 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- No major changes/additions to note + +Change Log 24.08.03 +^^^^^^^^^^^^^^^^^^^^ + +- ENH: Fix compile warnings in FilterUtilities. Init array in DataStore when resizing (#1026) [d534b18d] +- ENH: Update NXRunner error messages to provide instructions for .json files (#1032) [5aa8dd5f] +- ENH: Combine and Write STL Files - Allow user to select a Part Number Index to use for numbering. (#1024) [24a870f9] +- CI: Fixed python tests on asan CI (#1031) [8eccc1bf] +- CI: Updated nightly ASAN CI to use clang 14 (#1029) [37c3df57] +- CI: Update GitHub CI to newer GCC & Clang versions. (#1028) [f05b3781] +- BUG FIX: PeregrineHDF5Reader file system path and Array Type Fixes (#1025) [0332e709] +- ENH: Allow Crop Image Geometry to only crop a specific dimension (#1021) [c3be139e] +- BUG FIX: Remove Python plugin import error handling. (#1019) [b9d47447] +- BUG: Fix Reading Shift File in AlignSectionsList (#1018) [ed04c3ac] +- ENH: Various ReadPeregrineHDF5File Improvements (#1016) [8346cd36] +- Fixed C++20 issue with template id in constructor starting in gcc 11 (#1015) [c62fa7f8] +- ENH: Update required standard to C++20 (#1004) [31406a49] +- PERF: Inline Keyword and Anonymous Namespace Cleanup (#1013) [639460e9] +- DOC: ConvertHexGridToSquareGrid Doc Updates (#1014) [37e1159a] +- COMP: Fix compiler warnings in ComputeSurfaceFeaturesTest (#1003) [8bc16916] +- BUG: Fix out of core preferences file save bug (#1012) [5f1e159f] +- BUG: KAM messages should only be printed at 1 a second. (#1008) [a6324cac] +- FILTERS: Adding MeshIO reader and writers. (#1009) [74a06a32] +- Remove submodule for geometry creation helper methods. (#1007) [3af3fd55] +- ENH: Add the ability to resample images as they are read in as an image stack. (#1011) [a2aaa4cb] +- ENH: Renaming DataAnalysisToolkit to NXDataAnalysisToolkit. (#1010) [1d9a483a] +- FILTER: Add RemoveFlaggedEdges filter. Update other RemoveFlaggedXXX filters (#986) [d7190167] +- ENH: Include additional geometry examples and tests. (#1006) [365acfd8] +- FILTER: SliceTriangleGeometry & CreateAMScanPaths (#984) [8f241745] +- ENH: More explicit details when a parameter does not validate. (#1005) [34a1c054] +- ENH: Added a benchmark utility executable (#1002) [90feefba] +- ENH: Adjust warning text for 0 step value in InitializeDataArray (#999) [cec98fca] +- BUG: Update geometry find element functions to use static casting (#1000) [d86dbbdc] +- FILTER/ENH: DBSCAN Filter and Clustering Cleanup (#994) [e0d0cf26] +- ENH: Update Python Plugin Generation File Structure (#989) [40512e34] +- BUG: Update node based geometry 'findElementSizes(bool)' family of functions (#991) [baf97023] +- ENH: Reading OEM EBSD HDF5 Files should have better error messages generated (#996) [95f41e7b] +- ENH: Added DataStructure::getDataAsUnsafe functions (#998) [788e0736] +- Update vcpkg baseline for HDF5 1.14.4.3 (#997) [68d0e63f] +- DOCS: Create Python tutorial covering basic usage and filter writing (#925) [07dab90b] +- ENH: Small fixes for DREAM3D-NX RC-12 release (#988) [5592a973] +- ENH: Small fixes for RC-12 release [b7958b48] diff --git a/wrapping/python/plugins/NXDataAnalysisToolkit/conda/meta.yaml b/wrapping/python/plugins/NXDataAnalysisToolkit/conda/meta.yaml index b97cc633a7..bf75175714 100644 --- a/wrapping/python/plugins/NXDataAnalysisToolkit/conda/meta.yaml +++ b/wrapping/python/plugins/NXDataAnalysisToolkit/conda/meta.yaml @@ -11,22 +11,25 @@ source: build: noarch: python - script: {{ PYTHON }} -m pip install . -vv --no-deps --no-build-isolation + script: {{ PYTHON }} -m pip install {{ SRC_DIR }}/NXDataAnalysisToolkit -vv --no-deps --no-build-isolation number: 0 requirements: build: - - python >=3.10 + - python >=3.12 - pytest - pip + - hatchling run: - - python >=3.10 + - python >=3.12 - matplotlib - numpy - opencv - scipy - h5py - pillow + - meshio + - dream3dnx test: imports: @@ -35,8 +38,9 @@ test: - pip check requires: - pip + about: home: https://www.dream3d.io/ license: BSD - summary: DREAM3D-NX consists of data analysis tools (Filters) that allow for the construction of customized workflows (Pipelines) to analyze data. + summary: NXDataAnalysisToolkit is a python based plugin for DREAM3D-NX that adds additional filters. These filters can be used from DREAM3D-NX itself or from a python script.