diff --git a/wrapping/python/docs/source/Tutorial_1.rst b/wrapping/python/docs/source/Tutorial_1.rst index 4d56644686..ac89c13956 100644 --- a/wrapping/python/docs/source/Tutorial_1.rst +++ b/wrapping/python/docs/source/Tutorial_1.rst @@ -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 @@ -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 @@ -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: @@ -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 ` object. This @@ -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 @@ -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: @@ -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 @@ -265,7 +282,7 @@ And if you wanted to use `matplotlib `_ 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 @@ -276,93 +293,16 @@ to do this one would run the :ref:`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 diff --git a/wrapping/python/docs/source/Tutorial_2.rst b/wrapping/python/docs/source/Tutorial_2.rst index 96afbf4f0f..6d64905df9 100644 --- a/wrapping/python/docs/source/Tutorial_2.rst +++ b/wrapping/python/docs/source/Tutorial_2.rst @@ -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