Skip to content

Commit

Permalink
Updating the first tutorial a bit with section numbers:
Browse files Browse the repository at this point in the history
- Tried to have sphinx do it but the number overflows into titles and does not look good.

Signed-off-by: Michael Jackson <mike.jackson@bluequartz.net>
  • Loading branch information
imikejackson committed May 7, 2024
1 parent 8e15fcd commit f96ad46
Show file tree
Hide file tree
Showing 6 changed files with 64 additions and 33 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -75,7 +75,7 @@ Parameters ITKLabelContourImageFilter::parameters() const
params.insertSeparator(Parameters::Separator{"Input Parameter(s)"});
params.insert(std::make_unique<BoolParameter>(k_FullyConnected_Key, "Fully Connected",
"Set/Get whether the connected components are defined strictly by face connectivity or by face+edge+vertex connectivity. Default is FullyConnectedOff. "
"\note For objects that are 1 pixel wide, use FullyConnectedOn.",
"**NOTE** For objects that are 1 pixel wide, use FullyConnectedOn.",
false));
params.insert(std::make_unique<Float64Parameter>(k_BackgroundValue_Key, "Background Value",
"Set/Get the background value used to identify the objects and mark the pixels not on the border of the objects.", 0));
Expand Down
4 changes: 2 additions & 2 deletions wrapping/python/docs/source/Developer_API.rst
Original file line number Diff line number Diff line change
Expand Up @@ -112,7 +112,7 @@ General Parameters
~~~~~~~~~~~
The ``ArrayThresholdsParameter`` is used to specify thresholds for an array, allowing for filtering based on those thresholds.

This parameter holds a ArrayThresholdSet_ object and is used specifically for the :ref:`simplnx.MultiThresholdObjects() <MultiThresholdObjects>` filter.
This parameter holds a ArrayThresholdSet_ object and is used specifically for the :ref:`simplnx.MultiThresholdObjectsFilter() <MultiThresholdObjectsFilter>` filter.
This parameter should not be directly invoked but instead its ArrayThresholdSet_ is invoked and used.

Inputs
Expand Down Expand Up @@ -188,7 +188,7 @@ General Parameters
.. _ArrayThreshold:
.. py:class:: ArrayThresholdSet.ArrayThreshold
This class holds the values that are used for comparison in the :ref:`simplnx.MultiThresholdObjects() <MultiThresholdObjects>` filter.
This class holds the values that are used for comparison in the :ref:`simplnx.MultiThresholdObjectsFilter() <MultiThresholdObjectsFilter>` filter.

:ivar array_path: The :ref:`DataPath <DataPath>` to the array to use for this ArrayThreshold
:ivar comparison: Int. The comparison operator to use. 0=">", 1="<", 2="=", 3="!="
Expand Down
8 changes: 4 additions & 4 deletions wrapping/python/docs/source/Python_Introduction.rst
Original file line number Diff line number Diff line change
Expand Up @@ -156,7 +156,7 @@ external data sources into the DataArray.
npdata[:] = np.loadtxt(file_path, delimiter=',')
Within the **simplnx** code repository, there are example python files that can be used
as a starting point. `GitHub.com <https://github.com/bluequartzsoftware/simplnx/tree/develop/wrapping/python/examples>`_
as a starting point. `GitHub.com <https://github.com/BlueQuartzSoftware/simplnx/tree/develop/wrapping/python/examples/scripts>`_

Importing a .dream3d File
-------------------------
Expand Down Expand Up @@ -245,7 +245,7 @@ of the list of vertex values (XYZ as 32 bit floating point values) and the conne
list for the 1D, 2D and 3D geometries. :ref:`Please see the appropriate sections in the
manual for detailed descriptions. <Geometry Descriptions>`

There are working examples within the python file <https://www.github.com/bluequartzsoftware/simplnx/wrapping/python/examples/geometry_examples.py>.
There are working examples within the python file <https://github.com/BlueQuartzSoftware/simplnx/blob/develop/wrapping/python/examples/scripts/geometry_examples.py>.
The below code will create a TriangleGeometry by importing the vertices and triangle
connectivity from a sample file.

Expand Down Expand Up @@ -321,7 +321,7 @@ DataArray through the following:
The following code examples show how to create a simplnx DataArray and then use that array
as a numpy view.

The next code section was take from `basic_arrays.py <https://github.com/bluequartzsoftware/simplnx/tree/develop/wrapping/python/examples/basic_arrays.py>`__
The next code section was take from `basic_arrays.py <https://github.com/BlueQuartzSoftware/simplnx/blob/develop/wrapping/python/examples/scripts/basic_arrays.py>`__

.. code:: python
Expand All @@ -346,7 +346,7 @@ The next code section was take from `basic_arrays.py <https://github.com/bluequa
# Get the raw data as an Numpy View
npdata = data_structure[output_array_path].npview()
The next code section was take from `basic_arrays.py <https://github.com/bluequartzsoftware/simplnx/tree/develop/wrapping/python/examples/angle_conversion.py>`__
The next code section was take from `basic_arrays.py <https://github.com/BlueQuartzSoftware/simplnx/blob/develop/wrapping/python/examples/scripts/angle_conversion.py>`__

.. code:: python
Expand Down
55 changes: 33 additions & 22 deletions wrapping/python/docs/source/Tutorial_1.rst
Original file line number Diff line number Diff line change
@@ -1,19 +1,26 @@

.. _Tutorial_1:

=====================================
Tutorial 1: Basic Python Integration
=====================================

This tutorial is meant to be a very basic introduction to interacting with the DREAM3D-NX underlying library called 'simplnx'. This
tutorial will cover environment setup, minimal import statements and executing a few basic filters. Once you understand how to
execute a filter, all filters are generally setup the same way. Use the search feature on the web site to find the filter
tutorial will cover the following topics:

- Environment setup
- Minimal import statements
- Executing a few basic filters
- Accessing your data through a Numpy View

Once you understand how to execute a filter, all filters are generally setup the same way. Use the search feature on the web site to find the filter
that you are interested in running.

.. _Tutorial_1_Setup:

###################################
Anaconda Virtual Environment Setup
###################################
#########################################
1.1 Anaconda Virtual Environment Setup
#########################################

.. code:: shell
Expand All @@ -24,14 +31,14 @@ Anaconda Virtual Environment Setup
###################################
Introduction
1.2 Introduction
###################################

Setup your virtual environment following the directions from above. Then create a Tutorial_1.py file anywhere that you want and open that up in your Editor/IDE.


###################################
Necessary Import Statements
1.3 Necessary Import Statements
###################################

Just about every python source code that is written will need the following import Statements:
Expand All @@ -49,9 +56,9 @@ If you will be using filters from DREAM3D-NX's other plugins, then you may addit
import orientationanalysis as nxor
###################################
Creating the DataStructure Object
###################################
#########################################
1.4 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
simply done with the following line of code:
Expand All @@ -66,16 +73,16 @@ A few caveats to take note of:
2. Only a **single** :ref:`DataStructure` object can be stored in a .dream3d file.


################################################
First Steps: Create a Group in the DataStructure
################################################
######################################################
1.5 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
by instantiating the filter and then calling the `execute()` method with the appropriate parameters used in the call. With the current API, we are tending to
inline instantiate the filter and execute it all in the same line. Some things to note with this small piece of code:

- There will **always** be a required :ref:`DataStructure` object. All arguments in the `execute()` method are named arguments. None are positional. This means that each argument must be in the form of 'name=value'.
- The 2nd argument shows an use of the :ref:`DataPath` object. Lots of filters will require a :ref:`DataPath` object so this is a common use.
- The 2nd argument shows a use of the :ref:`DataPath` object. Lots of filters will require a :ref:`DataPath` object so this is a common use.
- There is a method called `hierarchy_to_str()` that is a part of the :ref:`DataStructure` class which will print the heirarchy of the DataStructure.


Expand All @@ -92,6 +99,10 @@ If we were to run this code we would get the following:
|--Top Level Group
****************************************
1.5.1 Adding Multiple Groups (Optional)
****************************************

Let's try to add a bunch of groups to the :ref:`DataStructure` object by using a loop:

.. code:: python
Expand All @@ -116,7 +127,7 @@ And the output would look like the following:
################################################
Result Objects
1.6 Result Objects
################################################

Each time a filter is executed, it will return a :ref:`nx.IFilter.ExecuteResult <result>` object. This
Expand Down Expand Up @@ -154,23 +165,23 @@ If you were to integrate this into your own code, then we would get the followin
################################################
Creating a DataArray Object
1.7 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
from the :ref:`DataArray`, enough to get the name, tuple shape and component shape. **ALL** interactions to modify a :ref:`DataArray` are done via a
`numpy view <https://numpy.org/doc/stable/user/basics.copies.html>`_. Let us first create a :ref:`DataArray` object within the :ref:`DataStructure` by using the
:ref:`CreateDataArray <CreateDataArray>` filter. Adding into the current python source file...
:ref:`CreateDataArrayFilter <CreateDataArrayFilter>` filter. Adding into the current python source file...

.. code:: python
result = nx.CreateDataArray().execute(data_structure=data_structure,
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"),
tuple_dimensions=[[5,4]])
nxutility.check_filter_result( nx.CreateDataArray(), result)
nxutility.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 @@ -188,7 +199,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.

################################################
Modifying the DataArray Object using Numpy
1.8 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 @@ -252,7 +263,7 @@ And if you wanted to use `matplotlib <https://matplotlib.org/>`_ to view the dat


################################################
Saving your Data to a .dream3d file
1.9 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 @@ -269,7 +280,7 @@ to do this one would run the :ref:`WriteDREAM3DFilter <WriteDREAM3DFilter>`. App
################################################
Complete Source Code
1.10 Complete Source Code
################################################

.. code:: python
Expand Down
22 changes: 21 additions & 1 deletion wrapping/python/docs/source/Tutorial_2.rst
Original file line number Diff line number Diff line change
@@ -1,13 +1,33 @@
.. section-numbering::

.. _Tutorial_2:

=====================================
Tutorial 2: Manipulating Pipelines
=====================================

###################################
Introduction
Part i
###################################

*******************
Chapter 1
*******************

Section 1
==========

Subsection
-----------


subsubsection
^^^^^^^^^^^^^^


Paragraph
""""""""""""""""

Setup your environment in the same way as from :ref:`Tutorial 1<Tutorial_1_Setup>`. In this tutorial we will
be manipulating a basic pipeline

6 changes: 3 additions & 3 deletions wrapping/python/docs/source/User_API.rst
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ General Parameters
.. _ArrayThresholdsParameter:
.. py:class:: ArrayThresholdsParameter
This parameter holds a ArrayThresholdSet_ object and is used specifically for the :ref:`simplnx.MultiThresholdObjects() <MultiThresholdObjects>` filter.
This parameter holds a ArrayThresholdSet_ object and is used specifically for the :ref:`simplnx.MultiThresholdObjectsFilter() <MultiThresholdObjectsFilter>` filter.
This parameter should not be directly invoked but instead it's ArrayThresholdSet_ is invoked and used.


Expand All @@ -76,7 +76,7 @@ General Parameters
.. _ArrayThreshold:
.. py:class:: ArrayThresholdSet.ArrayThreshold
This class holds the values that are used for comparison in the :ref:`simplnx.MultiThresholdObjects() <MultiThresholdObjects>` filter.
This class holds the values that are used for comparison in the :ref:`simplnx.MultiThresholdObjectsFilter() <MultiThresholdObjectsFilter>` filter.

:ivar array_path: The :ref:`DataPath <DataPath>` to the array to use for this ArrayThreshold
:ivar comparison: Int. The comparison operator to use. 0=">", 1="<", 2="=", 3="!="
Expand All @@ -101,7 +101,7 @@ General Parameters
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,
result = nx.MultiThresholdObjectsFilter.execute(data_structure=data_structure,
array_thresholds=threshold_set,
created_data_path="Mask",
created_mask_type=nx.DataType.boolean)
Expand Down

0 comments on commit f96ad46

Please sign in to comment.