Skip to content

Commit

Permalink
Update Tutorial 1, tweak tutorial 2.
Browse files Browse the repository at this point in the history 
Signed-off-by: Joey Kleingers <[email protected]>
  • Loading branch information
@joeykleingers @imikejackson
joeykleingers authored and imikejackson committed May 30, 2024
1 parent 3bcdbb2 commit e3690aa
Show file tree
Hide file tree
Showing 2 changed files with 35 additions and 95 deletions.
128 changes: 34 additions & 94 deletions wrapping/python/docs/source/Tutorial_1.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -57,9 +57,26 @@ If you will be using filters from DREAM3D-NX's other plugins, then you may addit
import itkimageprocessing as nxitk
import orientationanalysis as nxor
Also use these import statements:

.. code:: python
from pathlib import Path
import matplotlib.pyplot as plt
###################################
1.4 Set Output Directory
###################################

Set the output directory where the output from this tutorial will be stored, and create the directory. We are going to set the output directory in the same location as the current script.

.. code:: python
output_dir = Path(__file__).parent / 'Output' / 'Tutorial_1_Output'
output_dir.mkdir(exist_ok=True, parents=True)
#########################################
1.4 Creating the DataStructure Object
1.5 Creating the DataStructure Object
#########################################

If you will be interacting with data stored in DREAM3D-NX, you will need to instantiate a :ref:`DataStructure` object. This is
Expand All @@ -76,7 +93,7 @@ A few caveats to take note of:


######################################################
1.5 First Steps: Create a Group in the DataStructure
1.6 First Steps: Create a Group in the DataStructure
######################################################

As in the user interface of DREAM3D-NX, you as the developer can execute any of the filters from DREAM3D-NX using only Python codes. This is performed
Expand All @@ -102,7 +119,7 @@ If we were to run this code we would get the following:
****************************************
1.5.1 Adding Multiple Groups (Optional)
1.6.1 Adding Multiple Groups (Optional)
****************************************

Let's try to add a bunch of groups to the :ref:`DataStructure` object by using a loop:
Expand All @@ -129,7 +146,7 @@ And the output would look like the following:
################################################
1.6 Result Objects
1.7 Result Objects
################################################

Each time a filter is executed, it will return a :ref:`nx.IFilter.ExecuteResult <result>` object. This
Expand Down Expand Up @@ -167,7 +184,7 @@ If you were to integrate this into your own code, then we would get the followin
################################################
1.7 Creating a DataArray Object
1.8 Creating a DataArray Object
################################################

Raw data is stored in a :ref:`DataArray` object within the :ref:`DataStructure`. The DREAM3D-NX python bindings only expose a subset of functionality
Expand All @@ -179,11 +196,11 @@ from the :ref:`DataArray`, enough to get the name, tuple shape and component sha
result = nx.CreateDataArrayFilter().execute(data_structure=data_structure,
component_count=1,
initialization_value_str="0",
numeric_type_index=nx.NumericType.float32,
output_array_path=nx.DataPath("Top Level Group/2D Array"),
initialization_value="0",
numeric_type=nx.NumericType.float32,
output_data_array=nx.DataPath("Top Level Group/2D Array"),
tuple_dimensions=[[5,4]])
nxutility.check_filter_result( nx.CreateDataArrayFilter(), result)
check_filter_result( nx.CreateDataArrayFilter(), result)
print(f'{data_structure.hierarchy_to_str()}')
Note how we are creating the array inside the very first :ref:`DataGroup` that we created. If we run the file from start to finish we now get the following output:
Expand All @@ -201,7 +218,7 @@ Note how we are creating the array inside the very first :ref:`DataGroup` that w
As you can see we have successfully created an array that can hold some data. The next step is to interact with that :ref:`DataArray` and use numpy to modify the array in place.

################################################
1.8 Modifying the DataArray Object using Numpy
1.9 Modifying the DataArray Object using Numpy
################################################

The method from :ref:`DataStructure` that we will be using is item selection using the '[]' operator paired with an
Expand Down Expand Up @@ -265,7 +282,7 @@ And if you wanted to use `matplotlib <https://matplotlib.org/>`_ to view the dat


################################################
1.9 Saving your Data to a .dream3d file
1.10 Saving your Data to a .dream3d file
################################################

Most pipelines would want to save any modified data to a .dream3d file (if you are wanting the easiest compatibility with DREAM3D-NX). In order
Expand All @@ -276,93 +293,16 @@ to do this one would run the :ref:`WriteDREAM3DFilter <WriteDREAM3DFilter>`. App
# Use the WriteDREAM3DFilter to write out the modified DataStructure to disk
result = nx.WriteDREAM3DFilter.execute(data_structure=data_structure,
export_file_path="Output/lesson_4.dream3d",
export_file_path=str(output_dir / 'tutorial_1.dream3d'),
write_xdmf_file=False)
check_filter_result( nx.WriteDREAM3DFilter(), result)
################################################
1.10 Complete Source Code
################################################

.. code:: python
import simplnx as nx
import numpy as np
import matplotlib.pyplot as plt
import nxutility
#################
1.11 Full Example
#################

Full example of this tutorial is located at:

def check_filter_result(filter: nx.IFilter, result: nx.IFilter.ExecuteResult) -> None:
"""
This function will check the `result` for any errors. If errors do exist then a
`RuntimeError` will be thrown. Your own code to modify this to return something
else that doesn't just stop your script in its tracks.
"""
if len(result.warnings) != 0:
for w in result.warnings:
print(f'Warning: ({w.code}) {w.message}')
has_errors = len(result.errors) != 0
if has_errors:
for err in result.errors:
print(f'Error: ({err.code}) {err.message}')
raise RuntimeError(result)
else:
print(f"{filter.name()} :: No errors running the filter")
# #############################################################################
# Script Starts Here
# #############################################################################
# Create the DataStructure instance
data_structure = nx.DataStructure()
result = nx.CreateDataGroup.execute(data_structure=data_structure,
data_object_path=nx.DataPath("Top Level Group"))
check_filter_result(nx.CreateDataGroup(), result)
# Loop to create a bunch of DataGroups.
for i in range(1, 6):
current_data_group_path = nx.DataPath(f"Top Level Group {i}")
result = nx.CreateDataGroup.execute(data_structure=data_structure,
data_object_path=current_data_group_path)
check_filter_result(nx.CreateDataGroup(), result)
# Execute the CreateDataArray filter
result = nx.CreateDataArray().execute(data_structure=data_structure,
component_count=1,
initialization_value_str="0",
numeric_type_index=nx.NumericType.float32,
output_array_path=nx.DataPath("Top Level Group/2D Array"),
tuple_dimensions=[[4,5]])
check_filter_result(nx.CreateDataArray(), result)
print(f'{data_structure.hierarchy_to_str()}')
# Try to get the array from the DataStructure
try:
array_view = data_structure["Top Level Group/2D Array"].npview()
except AttributeError as attrerr:
print(f'{attrerr}')
quit(1) # This is pretty harsh! Maybe something more elegant to unwind from this error
# Fill the numpy data view with random numbers
rng = np.random.default_rng()
rng.standard_normal(out=array_view, dtype=np.float32)
print(f'{array_view}')
# Show the result
plt.imshow(array_view)
plt.title("Random Data")
plt.axis('off') # to turn off axes
plt.show()
# Use the WriteDREAM3DFilter to write out the modified DataStructure to disk
result = nx.WriteDREAM3DFilter.execute(data_structure=data_structure,
export_file_path="Output/tutorial_1.dream3d",
write_xdmf_file=False)
check_filter_result( nx.WriteDREAM3DFilter(), result)
https://github.com/BlueQuartzSoftware/NXWorkshop/blob/develop/PythonTutorial/tutorial_1.py

2 changes: 1 addition & 1 deletion wrapping/python/docs/source/Tutorial_2.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ Also use the following imports:
2.3 Set Output Directory
###################################

Set the output directory where the output from this tutorial will be stored, and create the directory.
Set the output directory where the output from this tutorial will be stored, and create the directory. We are going to set the output directory in the same location as the current script.

.. code:: python
Expand Down

0 comments on commit e3690aa

Please sign in to comment.