diff --git a/.all-contributorsrc b/.all-contributorsrc index 8b1f25116a..18918c37f2 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -66,7 +66,7 @@ }, { "login": "bpenniebq", - "name": "bpenniebq", + "name": "Braden Pennie", "avatar_url": "https://avatars.githubusercontent.com/u/106270421?v=4", "profile": "https://github.com/bpenniebq", "contributions": [ @@ -75,7 +75,7 @@ }, { "login": "john-stone-ics", - "name": "john-stone-ics", + "name": "John Stone", "avatar_url": "https://avatars.githubusercontent.com/u/18195504?v=4", "profile": "https://github.com/john-stone-ics", "contributions": [ @@ -100,6 +100,15 @@ "research", "data" ] + }, + { + "login": "ajacksonbq", + "name": "Alex Jackson", + "avatar_url": "", + "profile": "https://github.com/ajackson", + "contributions": [ + "code" + ] } ], "contributorsPerLine": 7, diff --git a/CMakeLists.txt b/CMakeLists.txt index a46dc91888..da6eb8ec21 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -876,7 +876,7 @@ set(PIPELINE_EXAMPLES_DEST_DIR "${PIPELINE_DEST_DIR}/Examples") if(SIMPLNX_DOWNLOAD_TEST_FILES AND TARGET SimplnxCore AND TARGET ITKImageProcessing AND TARGET OrientationAnalysis) add_custom_target(Copy_PorosityAnalysis_Pipelines ALL - COMMAND ${CMAKE_COMMAND} -E copy_if_different "${simplnx_SOURCE_DIR}/pipelines/PorosityAnalysis.d3dpipeline" "${PIPELINE_EXAMPLES_DEST_DIR}/PorosityAnalysis.d3dpipeline" + COMMAND ${CMAKE_COMMAND} -E copy_if_different "${simplnx_SOURCE_DIR}/pipelines/PorosityAnalysis.d3dpipeline" "${PIPELINE_EXAMPLES_DEST_DIR}/Examples/PorosityAnalysis.d3dpipeline" COMMENT "Copying Example Pipelines into Binary Directory" COMMAND_EXPAND_LISTS VERBATIM @@ -884,13 +884,21 @@ if(SIMPLNX_DOWNLOAD_TEST_FILES AND TARGET SimplnxCore AND TARGET ITKImageProcess set_target_properties(Copy_PorosityAnalysis_Pipelines PROPERTIES FOLDER ZZ_COPY_FILES) add_custom_target(Copy_CAxis_Pipelines ALL - COMMAND ${CMAKE_COMMAND} -E copy_if_different "${simplnx_SOURCE_DIR}/pipelines/Combo-EBSD-osc_r0c0.d3dpipeline" "${PIPELINE_EXAMPLES_DEST_DIR}/Combo-EBSD-osc_r0c0.d3dpipeline" + COMMAND ${CMAKE_COMMAND} -E copy_if_different "${simplnx_SOURCE_DIR}/pipelines/Combo-EBSD-osc_r0c0.d3dpipeline" "${PIPELINE_EXAMPLES_DEST_DIR}/Examples/Combo-EBSD-osc_r0c0.d3dpipeline" COMMENT "Copying Example Pipelines into Binary Directory" COMMAND_EXPAND_LISTS VERBATIM ) set_target_properties(Copy_CAxis_Pipelines PROPERTIES FOLDER ZZ_COPY_FILES) + # Install the pipeline files + install(FILES + "${simplnx_SOURCE_DIR}/pipelines/PorosityAnalysis.d3dpipeline" + "${simplnx_SOURCE_DIR}/pipelines/Combo-EBSD-osc_r0c0.d3dpipeline" + DESTINATION "pipelines/Examples" + COMPONENT Applications + ) + download_test_data(DREAM3D_DATA_DIR ${DREAM3D_DATA_DIR} ARCHIVE_NAME 6_6_caxis_data.tar.gz SHA512 6c3eefac62aecf3344de735c0df932dd9a2623653f39174ec72402c54e8911402ad9903ae2122bc23ff2dba8c94973b2882715908e1913973dff604b614a5293) add_custom_target(Copy_CAxis_Data ALL COMMAND ${CMAKE_COMMAND} -E tar xzf "${DREAM3D_DATA_DIR}/TestFiles/6_6_caxis_data.tar.gz" diff --git a/src/Plugins/SimplnxCore/docs/GeneratePythonSkeletonFilter.md b/src/Plugins/SimplnxCore/docs/GeneratePythonSkeletonFilter.md index 43a1237343..065eac26c3 100644 --- a/src/Plugins/SimplnxCore/docs/GeneratePythonSkeletonFilter.md +++ b/src/Plugins/SimplnxCore/docs/GeneratePythonSkeletonFilter.md @@ -1,46 +1,47 @@ -# Generate Python Plugin or Python Filter - -## Group - -Python +# Generate Python Plugin and/or Filters ## Description +The **Generate Python Plugin and/or Filters** is a powerful tool in the DREAM3D-NX environment that allows users to generate or update Python plugins and filter codes. This filter provides an interface for setting up and configuring Python filters within DREAM3D-NX pipelines, either by creating new plugins or by adding to existing ones. -This **Filter** generates the Python skeleton code for a new DREAM3D-NX/SIMPL-NX filters. These new Python filters can either be written to a newly generated Python plugin, or to an existing Python plugin. - -### Generating A New Plugin - -If the **Use Existing Plugin** parameter is OFF, then this filter will generate both a new Python skeleton plugin and new Python skeleton filters. - -The following parameters are available when **Use Existing Plugin** is OFF: - -+ Name of Plugin - The name of the plugin, referred to in the generated code. -+ Human Name of Plugin - The human-readable version of the plugin name. -+ Plugin Output Directory - The location on the file system where the plugin will be generated. -+ Filter Names - The names of filters that will be generated in the new plugin, separated by commas. - -### Using An Existing Plugin +## Usage -If the **Use Existing Plugin** parameter is ON, then this filter will generate new Python skeleton filters in an existing plugin. If the existing plugin was created manually and NOT created using this filter, some additional edits will need to be done in a few of the other plugin files. +### Configuration +The filter requires several parameters to be set, which dictate whether a new plugin is created or an existing one is modified. Key parameters include: -The following parameters are available when **Use Existing Plugin** is ON: +- `Use Existing Plugin`: A flag indicating whether to modify an existing plugin. +- `Name of Plugin`: The name of the plugin. +- `Human Name of Plugin`: A human-readable name for the plugin. +- `Existing Plugin Location`: The directory where the existing plugin is located (for updates). +- `Plugin Output Directory`: The directory where the new plugin will be stored. +- `Filter Names`: A list of filter names to be included in the plugin, separated by commas. -+ Existing Plugin Location - The file system path where the existing plugin is located. -+ Filter Names - The names of filters that will be generated in the existing plugin, separated by commas. +### Generating a New Plugin +To generate a new Python plugin: +1. Set `Use Existing Plugin` to `Off`. +2. Provide a `Name of Plugin`, `Human Name of Plugin`, `Plugin Output Directory`, and a list of `Filter Names`. +3. Execute the filter. It will generate the necessary plugin structure and files in the specified output directory. -**NOTE:** This option searches the existing plugin's **\_\_init\_\_.py** and **Plugin.py** files for the following comment tokens: +### Updating an Existing Plugin +To add filters to an existing Python plugin: +1. Set `Use Existing Plugin` to `On`. +2. Provide the `Existing Plugin Location` where the existing plugin is located. +3. Provide the `Name of Plugin`, `Human Name of Plugin`, and the list of `Filter Names` you wish to add. +4. Execute the filter. It will update the existing plugin with the new filters. -1. \# FILTER_INCLUDE_INSERT -2. \# FILTER_NAME_INSERT +#### Manual Plugin Creation -Both of these tokens are included in both files for any plugin that was originally generated using this filter. +If your plugin was not generated using the provided filter but was instead created manually, you may need to perform additional steps to ensure proper integration: -#### What if my plugin was created manually (not generated using this filter)? +1. **Python Import Statements**: + - In the absence of the `# FILTER_INCLUDE_INSERT` token, you must manually insert the Python import statements for the new filters into both the `__init__.py` file and the `Plugin.py` file. -+ If the **\# FILTER_INCLUDE_INSERT** token cannot be found, then the Python import statements for the new filters will need to be manually added to both files. -+ If the **\# FILTER_NAME_INSERT** token cannot be found, then each filter name will need to be manually added to the **all** and **get_filters** methods in the **\_\_init\_\_.py** and **Plugin.py** files, respectively. +2. **Filter Name Insertion**: + - If the `# FILTER_NAME_INSERT` token is missing, you need to manually add each filter name to specific methods in two files: + - In the `__init__.py` file, add to the `all` method. + - In the `Plugin.py` file, add to the `get_filters` method. ## Example Pipelines +None ## License & Copyright diff --git a/src/Plugins/SimplnxCore/src/SimplnxCore/Filters/GeneratePythonSkeletonFilter.cpp b/src/Plugins/SimplnxCore/src/SimplnxCore/Filters/GeneratePythonSkeletonFilter.cpp index 5e0c222ef1..9ac9ef6be9 100644 --- a/src/Plugins/SimplnxCore/src/SimplnxCore/Filters/GeneratePythonSkeletonFilter.cpp +++ b/src/Plugins/SimplnxCore/src/SimplnxCore/Filters/GeneratePythonSkeletonFilter.cpp @@ -38,7 +38,7 @@ Uuid GeneratePythonSkeletonFilter::uuid() const //------------------------------------------------------------------------------ std::string GeneratePythonSkeletonFilter::humanName() const { - return "Generate Python Plugin or Python Filter"; + return "Generate Python Plugin and/or Filters"; } //------------------------------------------------------------------------------ diff --git a/src/Plugins/SimplnxCore/wrapping/python/simplnxpy.cpp b/src/Plugins/SimplnxCore/wrapping/python/simplnxpy.cpp index 512fa20a15..0f9a9f4d0c 100644 --- a/src/Plugins/SimplnxCore/wrapping/python/simplnxpy.cpp +++ b/src/Plugins/SimplnxCore/wrapping/python/simplnxpy.cpp @@ -129,7 +129,7 @@ template auto BindNumberParameter(py::handle scope, const char* name) { auto numberParameter = py::class_(scope, name); - numberParameter.def(py::init()); + numberParameter.def(py::init(), "name"_a, "human_name"_a, "help_text"_a, "default_value"_a); return numberParameter; } @@ -137,8 +137,9 @@ template auto BindVectorParameter(py::handle scope, const char* name) { auto vectorParameter = py::class_(scope, name); - vectorParameter.def(py::init()); - vectorParameter.def(py::init()); + vectorParameter.def(py::init(), "name"_a, "human_name"_a, "help_text"_a, "default_value"_a); + vectorParameter.def(py::init(), "name"_a, "human_name"_a, + "help_text"_a, "default_value"_a, "names"_a); return vectorParameter; } diff --git a/wrapping/python/docs/index_template.rst b/wrapping/python/docs/index_template.rst index 08db500019..6a2fd23246 100644 --- a/wrapping/python/docs/index_template.rst +++ b/wrapping/python/docs/index_template.rst @@ -27,8 +27,10 @@ by creating a new virtual environment Overview DataObjects Geometry - API + User_API + Developer_API Python_Introduction + Writing_A_New_Python_Filter Reference_Frame_Notes ReleaseNotes_110 ReleaseNotes_120 diff --git a/wrapping/python/docs/source/Developer_API.rst b/wrapping/python/docs/source/Developer_API.rst new file mode 100644 index 0000000000..c7a9644e3a --- /dev/null +++ b/wrapping/python/docs/source/Developer_API.rst @@ -0,0 +1,1812 @@ +API for Developers +=================== + +General Parameters +------------------ + +.. _ArrayCreationParameter: +.. py:class:: ArrayCreationParameter + + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + ArrayCreationParameter(name: str, human_name: str, help_text: str, default_value: DataPath) + + Description + ~~~~~~~~~~~ + The ``ArrayCreationParameter`` is used to specify the creation of an array within the data structure. + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The unique, programmatic name of the parameter. This is the name used internally by the system to identify the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. This is the name presented to users and is meant to be more descriptive and user-friendly. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. This text is intended to guide the user in understanding the purpose of the parameter and how to use it. + - **Type**: string (str) + + - ``default_value`` : :ref:`DataPath ` + - **Description**: The default value for the parameter. For the `ArrayCreationParameter`, this is a :ref:`DataPath ` object that points to the location within the data structure where the data array will be created. + - **Type**: `DataPath` + + Usage + ~~~~~~ + + .. code:: python + + import simplnx as sx + + data_path = sx.DataPath(["Small IN100", "Scan Data", "Data"]) + params.insert(sx.ArrayCreationParameter(ExampleFilter2.PARAM5_KEY, 'Array Creation', 'Example array creation help text', data_path)) + +.. _ArraySelectionParameter: +.. py:class:: ArraySelectionParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + ArraySelectionParameter(name: str, human_name: str, help_text: str, default_value: DataPath, allowed_types: Set[DataType], required_comps: List[List[int]] = ..., location: ArraySelectionParameter.DataLocation = ...) + + Description + ~~~~~~~~~~~ + The ``ArraySelectionParameter`` is used for selecting an existing array within the data structure based on certain criteria. + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The unique, programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : :ref:`DataPath ` + - **Description**: The default DataPath pointing to the array to be selected. + - **Type**: `DataPath` + + - ``allowed_types`` : Set[DataType] + - **Description**: Set of allowed data types for the array. + - **Type**: Set of `DataType` + + - ``required_comps`` : List[List[int]] + - **Description**: List of component structures that are required. + - **Type**: List of lists of integers + + - ``location`` : ArraySelectionParameter.DataLocation + - **Description**: Location of the array (e.g., on nodes, cells, etc.). + - **Type**: `ArraySelectionParameter.DataLocation` + + Usage + ~~~~~~ + + .. code:: python + + import simplnx as sx + + data_path = sx.DataPath(["Small IN100", "Scan Data", "Data"]) + params.insert(sx.ArraySelectionParameter(ExampleFilter2.PARAM6_KEY, 'Array Selection', 'Example array selection help text', data_path, sx.get_all_data_types(), [[1]])) + +.. _ArrayThresholdsParameter: +.. py:class:: ArrayThresholdsParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + ArrayThresholdsParameter(name: str, human_name: str, help_text: str, default_value: ArrayThresholdSet, required_comps: List[List[int]] = ...) + + Description + ~~~~~~~~~~~ + 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() ` filter. + This parameter should not be directly invoked but instead its ArrayThresholdSet_ is invoked and used. + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The unique, programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : ArrayThresholdSet + - **Description**: The default set of thresholds for the array. + - **Type**: `ArrayThresholdSet` + + - ``required_comps`` : List[List[int]] + - **Description**: List of component structures that are required. + - **Type**: List of lists of integers + + + .. py:class:: ArrayThreshold + + Represents a single threshold, including the comparison type, array path, and the threshold value. + + - ``array_path`` : DataPath + - **Description**: Path to the data array. + - **Type**: `DataPath` + + - ``comparison`` : ArrayThreshold.ComparisonType + - **Description**: Type of comparison to perform (Equal, GreaterThan, LessThan, NotEqual). + - **Type**: `ArrayThreshold.ComparisonType` + + - ``value`` : float + - **Description**: The threshold value. + - **Type**: float + + .. py:class:: ArrayThreshold.ComparisonType + + Defines the types of comparisons that can be used in an `ArrayThreshold`. + + - ``Equal``, ``GreaterThan``, ``LessThan``, ``NotEqual`` + - **Description**: Types of comparison. + - **Type**: Enum (int) + + .. py:class:: ArrayThresholdSet + + Represents a set of `ArrayThreshold` objects. + + - ``thresholds`` : List[IArrayThreshold] + - **Description**: List of `ArrayThreshold` objects that make up the set. + - **Type**: List of `IArrayThreshold` + + Usage + ~~~~~~ + .. code:: python + + import simplnx as sx + + params.insert(sx.ArrayThresholdsParameter('data_thresholds_key', 'Data Thresholds', 'DataArray thresholds to mask', sx.ArrayThresholdSet())) + +.. _ArrayThresholdSet: +.. py:class:: ArrayThresholdSet + + This class holds a list of ArrayThreshold_ objects. + + :ivar thresholds: List[ArrayThreshold_] objects + +.. _ArrayThreshold: +.. py:class:: ArrayThresholdSet.ArrayThreshold + + This class holds the values that are used for comparison in the :ref:`simplnx.MultiThresholdObjects() ` filter. + + :ivar array_path: The :ref:`DataPath ` to the array to use for this ArrayThreshold + :ivar comparison: Int. The comparison operator to use. 0=">", 1="<", 2="=", 3="!=" + :ivar value: Numerical Value. The value for the comparison + + The below code will create an ArrayThresholdSet_ that is used to create a "Mask" output array of type boolean that will mark + each value in its output array as "True" if **both** of the ArrayThreshold Objects evaluate to True. Specifically, the "Confidence Index" and "Image Quality" + array MUST have the same number of Tuples and the output "Mask" array will also have the same number of tuples. + + .. code:: python + + threshold_1 = cx.ArrayThreshold() + threshold_1.array_path = cx.DataPath(["Small IN100", "Scan Data", "Confidence Index"]) + threshold_1.comparison = cx.ArrayThreshold.ComparisonType.GreaterThan + threshold_1.value = 0.1 + + threshold_2 = cx.ArrayThreshold() + threshold_2.array_path = cx.DataPath(["Small IN100", "Scan Data", "Image Quality"]) + threshold_2.comparison = cx.ArrayThreshold.ComparisonType.GreaterThan + threshold_2.value = 120 + + threshold_set = cx.ArrayThresholdSet() + threshold_set.thresholds = [threshold_1, threshold_2] + result = cx.MultiThresholdObjects.execute(data_structure=data_structure, + array_thresholds=threshold_set, + created_data_path="Mask", + created_mask_type=cx.DataType.boolean) + +.. _AttributeMatrixSelectionParameter: +.. py:class:: AttributeMatrixSelectionParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + AttributeMatrixSelectionParameter(name: str, human_name: str, help_text: str, default_value: DataPath) + + Description + ~~~~~~~~~~~ + The ``AttributeMatrixSelectionParameter`` is used for selecting an Attribute Matrix within the data structure. + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The unique, programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : :ref:`DataPath ` + - **Description**: The default DataPath pointing to the Attribute Matrix to be selected. + - **Type**: `DataPath` + + Usage + ~~~~~~ + + .. code:: python + + import simplnx as sx + + params.insert(sx.AttributeMatrixSelectionParameter('cell_attr_matrix_key', "Cell Attribute Matrix", "Example attribute matrix selection help text", sx.DataPath(["Image Geometry", "Cell Data"]))) + +.. _BoolParameter: +.. py:class:: BoolParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + BoolParameter(name: str, human_name: str, help_text: str, default_value: bool) + + Description + ~~~~~~~~~~~ + The ``BoolParameter`` is used to toggle between two states, true or false. + + This parameter can be linked to other parameters so that the other parameters' availability depends on the current state of this parameter. + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The unique, programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : bool + - **Description**: The default boolean value (true or false) for the parameter. + - **Type**: boolean (bool) + + General Usage + ~~~~~~~~~~~~~ + + .. code-block:: python + + import simplnx as sx + + params.insert(sx.BoolParameter('example_bool_key', 'Bool Parameter', 'Example bool help text', False)) + + Linked Usage + ~~~~~~~~~~~~~ + The following example sets up a BoolParameter so that it toggles the availability of a DataGroupSelectionParameter. + + .. code-block:: python + + import simplnx as sx + + params.insert_linkable_parameter(sx.BoolParameter('example_bool_key', 'Bool Parameter', 'Example bool help text', True)) + params.insert(sx.DataGroupSelectionParameter('example_data_group_selection_key', 'DataGroupSelectionParameter', 'Example data group selection help text', sx.DataPath([]), set([sx.BaseGroup.GroupType.DataGroup]))) + + params.link_parameters('example_bool_key', 'example_data_group_selection_key', True) + +.. _CalculatorParameter: +.. py:class:: CalculatorParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + CalculatorParameter(name: str, human_name: str, help_text: str, default_value: CalculatorParameter.ValueType) + + Description + ~~~~~~~~~~~ + The ``CalculatorParameter`` is used to execute mathematical expressions on data arrays and other data objects. + + This parameter has a single member type "ValueType" that can be constructed with the necessary values. + + .. py:class:: CalculatorParameter.ValueType + + :ivar selected_group: The :ref:`DataGroup` or :ref:`AttributeMatrix` that contains the :ref:`DataArray ` that will be used in the equations + :ivar equation: String. The equation that will be evaluated + :ivar units: cx.CalculatorParameter.AngleUnits.Radians or cx.CalculatorParameter.AngleUnits.Degrees + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The unique, programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : CalculatorParameter.ValueType + - **Description**: The default value or expression for the calculator parameter. + - **Type**: `CalculatorParameter.ValueType` + - **Internal Data**: The values that are contained within the CalculatorParameter.ValueType. + - selected_group: The :ref:`DataGroup` or :ref:`AttributeMatrix` that contains the :ref:`DataArray ` that will be used in the equations. + - equation: String. The equation that will be evaluated. + - units: sx.CalculatorParameter.AngleUnits.Radians or sx.CalculatorParameter.AngleUnits.Degrees + + Usage + ~~~~~~ + + .. code-block:: python + + import simplnx as sx + + calc_param = sx.CalculatorParameter.ValueType( sx.DataPath(["Small IN100","Scan Data"]), "Confidence Index * 10", sx.CalculatorParameter.AngleUnits.Radians) + params.insert(sx.CalculatorParameter(ExampleFilter2.PARAM18_KEY, "CalculatorParameter", "Example help text for calculator parameter", calc_param)) + +.. _ChoicesParameter: +.. py:class:: ChoicesParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + ChoicesParameter(name: str, human_name: str, help_text: str, default_value: int, choices: List[str]) + + Description + ~~~~~~~~~~~ + The ``ChoicesParameter`` is used to provide a string selection from a list of predefined choices. + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The unique, programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : int + - **Description**: The default selected index (from the list of choices) for the parameter. + - **Type**: integer (int) + + - ``choices`` : List[str] + - **Description**: The list of available choices for the parameter. + - **Type**: List of strings (List[str]) + + General Usage + ~~~~~~~~~~~~~ + + .. code-block:: python + + import simplnx as sx + + params.insert(sx.ChoicesParameter('example_choices_key', 'Choices Parameter', 'Example choices help text', 0, ["foo", "bar", "baz"])) + + Linked Usage + ~~~~~~~~~~~~~ + The following example sets up a ChoicesParameter so that it toggles the availability of a DataPathSelectionParameter based on whether or not the ChoicesParameter is set to the second choice. + + .. code-block:: python + + import simplnx as sx + + params.insert_linkable_parameter(sx.ChoicesParameter('example_choices_key', 'Choices Parameter', 'Example choices help text', 0, ["foo", "bar", "baz"])) + params.insert(sx.DataPathSelectionParameter('example_data_path_selection_key', 'DataPathSelectionParameter', 'Example data path selection help text', sx.DataPath([]))) + + params.link_parameters('example_choices_key', 'example_data_path_selection_key', 1) + +.. _DataGroupCreationParameter: +.. py:class:: DataGroupCreationParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + DataGroupCreationParameter(name: str, human_name: str, help_text: str, default_value: DataPath) + + Description + ~~~~~~~~~~~ + The ``DataGroupCreationParameter`` is used to specify the creation of a data group within the data structure. + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The unique, programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : :ref:`DataPath ` + - **Description**: The default DataPath for the data group to be created. + - **Type**: `DataPath` + + Usage + ~~~~~~ + + .. code-block:: python + + import simplnx as sx + + params.insert(sx.DataGroupCreationParameter('example_data_group_creation_key', 'DataGroupCreationParameter', 'Example data group creation help text', sx.DataPath([]))) + +.. _DataGroupSelectionParameter: +.. py:class:: DataGroupSelectionParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + DataGroupSelectionParameter(name: str, human_name: str, help_text: str, default_value: DataPath, allowed_types: Set[BaseGroup.GroupType]) + + Description + ~~~~~~~~~~~ + The ``DataGroupSelectionParameter`` is used for selecting an existing data group within the data structure based on a set of allowed group types. + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The unique, programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : :ref:`DataPath ` + - **Description**: The default DataPath pointing to the data group to be selected. + - **Type**: `DataPath` + + - ``allowed_types`` : Set[BaseGroup.GroupType] + - **Description**: Set of allowed group types for the data group. + - **Type**: Set of `BaseGroup.GroupType` + + Usage + ~~~~~~ + + .. code-block:: python + + import simplnx as sx + + params.insert(sx.DataGroupSelectionParameter('example_data_group_selection_key', 'DataGroupSelectionParameter', 'Example data group selection help text', sx.DataPath([]), set([sx.BaseGroup.GroupType.DataGroup]))) + +.. _DataObjectNameParameter: +.. py:class:: DataObjectNameParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + DataObjectNameParameter(name: str, human_name: str, help_text: str, default_value: str) + + Description + ~~~~~~~~~~~ + The ``DataObjectNameParameter`` is used to specify the name of a data object within the data structure. + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The unique, programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : str + - **Description**: The default name for the data object. + - **Type**: string (str) + + Usage + ~~~~~~ + + .. code-block:: python + + import simplnx as sx + + params.insert(sx.DataObjectNameParameter('data_object_name_key', "DataObjectNameParameter", "Example help text for DataObjectNameParameter", "Data Group")) + +.. _DataPathSelectionParameter: +.. py:class:: DataPathSelectionParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + DataPathSelectionParameter(name: str, human_name: str, help_text: str, default_value: DataPath) + + Description + ~~~~~~~~~~~ + The ``DataPathSelectionParameter`` is used for selecting a :ref:`DataPath ` to a data object within the :ref:`DataStructure`. + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The unique, programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : :ref:`DataPath ` + - **Description**: The default DataPath to be selected. + - **Type**: `DataPath` + + Usage + ~~~~~~ + + .. code-block:: python + + import simplnx as sx + + params.insert(sx.DataPathSelectionParameter('example_data_path_key', 'DataPathSelectionParameter', 'Example data path selection help text', sx.DataPath([]))) + +.. _DataStoreFormatParameter: +.. py:class:: DataStoreFormatParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + DataStoreFormatParameter(name: str, human_name: str, help_text: str, default_value: str) + + Description + ~~~~~~~~~~~ + The ``DataStoreFormatParameter`` is used to specify the format of a :ref:`DataStore` within the data structure. + + Depending on the version of simplnx being used, there can be both in-core and out-of-core :ref:`DataStore` objects available. + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The unique, programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : str + - **Description**: The default format for the data store. + - **Type**: string (str) + + Usage + ~~~~~~ + + .. code-block:: python + + import simplnx as sx + + params.insert(sx.DataStoreFormatParameter('data_store_format_key', 'Data Store Format', 'This value will specify which data format is used by the array\'s data store. An empty string results in in-memory data store.', "")) + +.. _DataTypeParameter: +.. py:class:: DataTypeParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + DataTypeParameter(name: str, human_name: str, help_text: str, default_value: DataType) + + Description + ~~~~~~~~~~~ + The ``DataTypeParameter`` is used to specify the type of data for a particular operation or data structure element. + + This parameter holds an enumeration value that represents the numerical type for created arrays. The possible values are: + + .. code:: python + + cx.DataType.int8 + cx.DataType.uint8 + cx.DataType.int16 + cx.DataType.uint16 + cx.DataType.int32 + cx.DataType.uint32 + cx.DataType.int64 + cx.DataType.uint64 + cx.DataType.float32 + cx.DataType.float64 + cx.DataType.boolean + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The unique, programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : DataType + - **Description**: The default data type. + - **Type**: `DataType` + + Usage + ~~~~~~ + + .. code-block:: python + + import simplnx as sx + + params.insert(sx.DataTypeParameter('data_type_key', "Data Type", "Example data type help text", sx.DataType.float64)) + +.. _Dream3dImportParameter: +.. py:class:: Dream3dImportParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + Dream3dImportParameter(name: str, human_name: str, help_text: str, default_value: Dream3dImportParameter.ImportData) + + Description + ~~~~~~~~~~~ + The ``Dream3dImportParameter`` holds the information necessary to import a .dream3d file through the **ImportData** object. + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The unique, programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : Dream3dImportParameter.ImportData + - **Description**: The default import data setting for DREAM3D. + - **Type**: `Dream3dImportParameter.ImportData` + - **Internal Data**: + - **file_path**: Path to the .dream3d file on the file system + - **data_paths**: List of :ref:`DataPath ` objects. Use the python 'None' value to indicate that you want to read **ALL** the data from file. + + Usage + ~~~~~~ + + .. code-block:: python + + import simplnx as sx + + import_data = sx.Dream3dImportParameter.ImportData() + import_data.file_path = "/private/tmp/basic_ebsd.dream3d" + import_data.data_paths = None + params.insert(sx.Dream3dImportParameter('import_file_path_key', "Import File Path", "The HDF5 file path the DataStructure should be imported from.", import_data)) + +.. _DynamicTableParameter: +.. py:class:: DynamicTableParameter + + Declarations + ~~~~~~~~~~~~ + .. code-block:: python + + DynamicTableParameter(name: str, human_name: str, help_text: str, default_value: List[List[float]], table_info: DynamicTableInfo) + + DynamicTableParameter(name: str, human_name: str, help_text: str, table_info: DynamicTableInfo) + + Description + ~~~~~~~~~~~ + The ``DynamicTableParameter`` is used to specify parameters for dynamic tables which can be modified by the user during runtime. It involves detailed configuration of rows and columns using the `DynamicTableInfo` class. + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The unique, programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : List[List[float]] + - **Description**: The default value for the dynamic table, typically a list of lists representing the table rows and columns. + - **Type**: List of lists of floats (List[List[float]]) + + - ``table_info`` : DynamicTableInfo + - **Description**: Configuration information for the dynamic table, including row and column details. + - **Type**: `DynamicTableInfo` + + .. py:class:: DynamicTableInfo + + Used to provide detailed configuration for the dynamic table's rows and columns. It includes the following nested classes: + + .. py:class:: DynamicVectorInfo + + - Used to specify dynamic rows or columns where the size can be adjusted. + - **Methods**: + - ``__init__(self, min_size: int, default_size: int, header_template: str)``: Initialize with minimum size, default size, and a header template. + - ``__init__(self, min_size: int, header_template: str)``: Initialize with minimum size and a header template. + + .. py:class:: StaticVectorInfo + + - Used to specify static rows or columns with a fixed size or predefined headers. + - **Methods**: + - ``__init__(self, size: int)``: Initialize with a fixed size. + - ``__init__(self, headers: List[str])``: Initialize with predefined headers. + + .. py:class:: VectorInfo + + - Used as a wrapper to specify information about either static or dynamic rows/columns. + - **Methods**: + - ``__init__(self, vector_info: DynamicTableInfo.StaticVectorInfo)``: Initialize with static vector information. + - ``__init__(self, vector_info: DynamicTableInfo.DynamicVectorInfo)``: Initialize with dynamic vector information. + + - **Methods**: + - ``__init__(self)``: Initialize without specific row/column information. + - ``__init__(self, rows_info: DynamicTableInfo.VectorInfo, cols_info: DynamicTableInfo.VectorInfo)``: Initialize with specific information for rows and columns. + - ``set_cols_info(self, info: DynamicTableInfo.VectorInfo)``: Set information for columns. + - ``set_rows_info(self, info: DynamicTableInfo.VectorInfo)``: Set information for rows. + + Usage + ~~~~~~ + + .. code-block:: python + + import simplnx as sx + + default_table = [[10, 20], [30, 40]] + row_info = sx.DynamicTableInfo.DynamicVectorInfo(0, "Row {}") + col_info = sx.DynamicTableInfo.DynamicVectorInfo(2, "Col {}") + dynamic_table_info = sx.DynamicTableInfo(sx.DynamicTableInfo.VectorInfo(row_info), sx.DynamicTableInfo.VectorInfo(col_info)) + params.insert(sx.DynamicTableParameter('dynamic_table', 'DynamicTableParameter', 'DynamicTableParameter Example Help Text', default_table, dynamic_table_info)) + +.. _EnsembleInfoParameter: +.. py:class:: EnsembleInfoParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + EnsembleInfoParameter(name: str, human_name: str, help_text: str, default_value) + + Description + ~~~~~~~~~~~ + The ``EnsembleInfoParameter`` is used to represent a list of 3 value lists. Each list holds 3 values, Crystal Structure, Phase Type, Phase Name. + + Each row represents a specific phase. + + The valid values for the **Crystal Structures** are: + + - "Hexagonal-High 6/mmm" + - "Cubic-High m-3m" + - "Hexagonal-Low 6/m" + - "Cubic-Low m-3 (Tetrahedral)" + - "Triclinic -1" + - "Monoclinic 2/m" + - "Orthorhombic mmm" + - "Tetragonal-Low 4/m" + - "Tetragonal-High 4/mmm" + - "Trigonal-Low -3", + - "Trigonal-High -3m" + + The valid **Phase Types** are: + + - "Primary" + - "Precipitate" + - "Transformation" + - "Matrix" + - "Boundary" + + The user can define their own phase names. + + This is used in combination with the :ref:`OrientationAnalysis.CreateEnsembleInfoFilter() ` filter. + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The unique, programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` + - **Description**: The default value for the ensemble information. + - **Type**: Varies (type is context-dependent) + + Usage + ~~~~~~ + + .. code-block:: python + + import simplnx as sx + + ensemble_info = [] + ensemble_info.append(["Hexagonal-High 6/mmm","Primary","Phase 1"]) + ensemble_info.append(["Cubic-High m-3m","Primary","Phase 2"]) + params.insert(sx.EnsembleInfoParameter('created_ensemble_info_key', "Created Ensemble Info", "The values with which to populate the crystal structures, phase types, and phase names data arrays. Each row corresponds to an ensemble phase.", ensemble_info)) + +.. _FileSystemPathParameter: +.. py:class:: FileSystemPathParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + FileSystemPathParameter(name: str, human_name: str, help_text: str, default_value: os.PathLike, extensions_type: Set[str], path_type: FileSystemPathParameter.PathType, accept_all_extensions: bool = ...) + + Description + ~~~~~~~~~~~ + The ``FileSystemPathParameter`` is used to specify a file system path, allowing the user to select directories or files for input or output operations. + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The unique, programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : os.PathLike + - **Description**: The default path. + - **Type**: `os.PathLike` + + - ``extensions_type`` : Set[str] + - **Description**: Set of allowed file extensions. + - **Type**: Set of strings (Set[str]) + + - ``path_type`` : FileSystemPathParameter.PathType + - **Description**: The type of path (InputDir, InputFile, OutputDir, OutputFile). + - **Type**: `FileSystemPathParameter.PathType` + + - ``accept_all_extensions`` : bool + - **Description**: Flag indicating whether all file extensions are acceptable. + - **Type**: boolean (bool) + + Usage + ~~~~~~ + + .. code-block:: python + + import simplnx as sx + + params.insert(sx.FileSystemPathParameter('input_dir', 'Input Directory', 'Example input directory help text', 'Data', set(), sx.FileSystemPathParameter.PathType.InputDir)) + params.insert(sx.FileSystemPathParameter('input_file', 'Input File', 'Example input file help text', '/opt/local/bin/ninja', set(), sx.FileSystemPathParameter.PathType.InputFile, True)) + params.insert(sx.FileSystemPathParameter('output_dir', 'Output Directory', 'Example output directory help text', 'Output Data', set(), sx.FileSystemPathParameter.PathType.OutputDir)) + params.insert(sx.FileSystemPathParameter('output_file', 'Output File', 'Example output file help text', '', set(), sx.FileSystemPathParameter.PathType.OutputFile)) + +.. _GenerateColorTableParameter: +.. py:class:: GenerateColorTableParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + GenerateColorTableParameter(name: str, human_name: str, help_text: str, default_value: Json) + + Description + ~~~~~~~~~~~ + **NOTE: THIS API IS GOING TO CHANGE IN A FUTURE UPDATE** + + The ``GenerateColorTableParameter`` is used to specify parameters for generating color tables, typically used in visualization or data representation. + + This parameter is used specifically for the :ref:`simplnx.GenerateColorTableFilter() ` filter. + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The unique, programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : Json + - **Description**: The default color table in JSON format. + - **Type**: `Json` + + .. attribute:: simplnx.Json + + This value encapsulates a string that represents well formed JSON. It can be constructed on-the-fly as follows: + + .. code:: python + + color_control_points = cx.Json('{"RGBPoints": [0,0,0,0,0.4,0.901960784314,0,0,0.8,0.901960784314,0.901960784314,0,1,1,1,1]}') + + Usage + ~~~~~~ + + .. code-block:: python + + import simplnx as sx + + color_control_points = sx.Json('{"RGBPoints": [0,0,0,0,0.4,0.901960784314,0,0,0.8,0.901960784314,0.901960784314,0,1,1,1,1]}') + params.insert(sx.GenerateColorTableParameter('color_table_preset_key', "Select Preset...", "Select a preset color scheme to apply to the created array", color_control_points)) + +.. _GeneratedFileListParameter: +.. py:class:: GeneratedFileListParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + GeneratedFileListParameter(name: str, human_name: str, help_text: str, default_value: GeneratedFileListParameter.ValueType) + + Description + ~~~~~~~~~~~ + The ``GeneratedFileListParameter`` is used to specify parameters for generating a list of file paths, typically used in batch processing or automated file generation. + + In order to instantiate this parameter, the programmer should use the ``GeneratedFileListParameter.ValueType`` data member. + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The unique, programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : GeneratedFileListParameter.ValueType + - **Description**: The default configuration for generating the file list. + - **Type**: `GeneratedFileListParameter.ValueType` + + .. py:class:: GeneratedFileListParameter.Ordering + + Enumeration that defines the ordering of the generated file list. + + - ``HighToLow``, ``LowToHigh`` + - **Description**: Determines the ordering of the files in the generated list. + - **Type**: Enum (int) + + .. py:class:: GeneratedFileListParameter.ValueType + + Represents the configuration for the generated file list. + + - **Fields**: + - ``start_index`` : int + - **Description**: The start index for the file list generation. + - ``end_index`` : int + - **Description**: The end index for the file list generation (inclusive). + - ``file_extension`` : str + - **Description**: The file extension of the input files including the "." character. + - ``file_prefix`` : str + - **Description**: The string part of the file name that appears **before** the index digits. + - ``file_suffix`` : str + - **Description**: The string part of the file anem that appears **after** the index digits. + - ``increment_index`` : int + - **Description**: The value that determines how much to increment the index value when generating the file list. + - ``input_path`` : str + - **Description**: The file system path to the directory that contains the input files + - ``ordering`` : GeneratedFileListParameter.Ordering + - **Description**: The ordering of the generated files (HighToLow or LowToHigh). + - ``padding_digits`` : int + - **Description**: The number of digits used for padding the file index. + + - **Methods**: + - ``generate()``: Generates the list of file names. + - ``generate_and_validate(arg0: bool)``: Generates the list of file names and validates them based on the provided argument. + + Usage + ~~~~~~ + + If you have a stack of images in tif format numbered from 11 to 174 where there are only 2 digits for slice indices \< 100 and 3 digits after 100, the breakdown of the file name is as follows: + + +------------------------+--------------------------+--------+-----------+ + | Prefix | index and padding digits | suffix | extension | + +========================+==========================+========+===========+ + | slice- | 100 | _Data | .tif | + +------------------------+--------------------------+--------+-----------+ + + The python code to implement this scheme is as follows: + + .. code-block:: python + + import simplnx as sx + + generated_file_list_value = sx.GeneratedFileListParameter.ValueType() + generated_file_list_value.input_path = "DREAM3DNXData/Data/Porosity_Image" + generated_file_list_value.ordering = sx.GeneratedFileListParameter.Ordering.LowToHigh + generated_file_list_value.file_prefix = "slice-" + generated_file_list_value.file_suffix = "" + generated_file_list_value.file_extension = ".tif" + generated_file_list_value.start_index = 11 + generated_file_list_value.end_index = 174 + generated_file_list_value.increment_index = 1 + generated_file_list_value.padding_digits = 2 + params.insert(sx.GeneratedFileListParameter('input_file_list_key', "Input File List", "The list of files to be read", generated_file_list_value)) + +.. _GeometrySelectionParameter: +.. py:class:: GeometrySelectionParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + GeometrySelectionParameter(name: str, human_name: str, help_text: str, default_value: DataPath, allowed_types: Set[IGeometry.Type]) + + Description + ~~~~~~~~~~~ + The ``GeometrySelectionParameter`` is used to specify a valid :ref:`simplnx.Geometry() ` selection within the data structure, constrained by allowed geometry types. + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The unique, programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : :ref:`DataPath ` + - **Description**: The default path to the geometry data. + - **Type**: `DataPath` + + - ``allowed_types`` : Set[IGeometry.Type] + - **Description**: The set of allowed geometry types for the selection. + - **Type**: Set of `IGeometry.Type` + + .. attribute:: IGeometry.Type + + Defines the allowed types of geometry data that can be chosen. + + - ``Edge``: Represents edge geometry. + - ``Hexahedral``: Represents hexahedral geometry. + - ``Image``: Represents image geometry. + - ``Quad``: Represents quad geometry. + - ``RectGrid``: Represents rectangular grid geometry. + - ``Tetrahedral``: Represents tetrahedral geometry. + - ``Triangle``: Represents triangle geometry. + - ``Vertex``: Represents vertex geometry. + + Usage + ~~~~~~ + + .. code-block:: python + + import simplnx as sx + + params.insert(sx.GeometrySelectionParameter('example_geometry_selection_parameter', 'GeometrySelectionParameter', 'Example geometry selection help text', sx.DataPath([]), set([sx.IGeometry.Type.Image, sx.IGeometry.Type.RectGrid]))) + +.. _ReadCSVFileParameter: +.. py:class:: ReadCSVFileParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + ReadCSVFileParameter(self, name: str, human_name: str, help_text: str, default_value: ReadCSVDataParameter) + + Description + ~~~~~~~~~~~ + The ``ReadCSVFileParameter`` is used to specify parameters for reading data from a CSV (Comma-Separated Values) file using a `ReadCSVDataParameter` instance for detailed configuration. + + + The file can be comma, space, tab or semicolon separated. + + The file optionally can have a line of headers. The user can specify what line number the header is located. + + The import can start at a user specified line number and will continue importing lines equal to the total number of tuples that the user specified. + + The primary python object that will hold the parameter information is the `ReadCSVDataParameter` class described below. + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The unique, programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : ReadCSVDataParameter + - **Description**: The default configuration for reading the CSV file. + - **Type**: `ReadCSVDataParameter` + + .. py:class:: ReadCSVDataParameter + + The ReadCSVDataParameter class holds all the necessary information to import a CSV formatted file into DREAM3D-NX. There are + a number of member variables that need to be set correctly before passing it into the filter parameter as the default value. + + - ``column_data_types`` : List[DataType] + - **Description**: The data types of the columns in the CSV file. Indicates the kind of native numerical values (int, float... ) that will be used in the created :ref:`DataArray `. + - **Type**: List of :ref:`cx.DataType` + + - ``consecutive_delimiters`` : bool + - **Description**: Flag indicating whether consecutive delimiters should be treated as a single delimiter. + - **Type**: boolean (bool) + + - ``custom_headers`` : List[str] + - **Description**: Custom headers to use if the header mode is set to Custom. + - **Type**: List of strings (List[str]) + + - ``delimiters`` : List[str] + - **Description**: The delimiters used in the CSV file. + - **Type**: List of strings (List[str]) + + - ``header_mode`` : ReadCSVDataParameter.HeaderMode + - **Description**: The mode used for parsing headers in the CSV file (Custom or Line). + - **Type**: `ReadCSVDataParameter.HeaderMode` + + - ``headers_line`` : int + - **Description**: The line number where headers are located, used if the header mode is set to Line. One-based indexing. + - **Type**: integer (int) + + - ``input_file_path`` : str + - **Description**: The file path to the input CSV file. + - **Type**: string (str) + + - ``skipped_array_mask`` : List[bool] + - **Description**: Booleans, one per column, that indicate whether or not to skip importing each created :ref:`DataArray `. + - **Type**: List of booleans (List[bool]) + + - ``start_import_row`` : int + - **Description**: The row number from which to start importing data. One-based indexing. + - **Type**: integer (int) + + - ``tuple_dims`` : List[int] + - **Description**: The tuple dimensions for the created :ref:`DataArrays `. + - **Type**: List of integers (List[int]) + + ``ReadCSVDataParameter.HeaderMode`` Enum + ---------------------------------------- + Defines the modes for parsing headers in the CSV file. + + - ``Custom``, ``Line`` + - **Description**: Determines how headers are parsed (Custom: use custom headers, Line: use headers from a specific line). + - **Type**: Enum (int) + + Usage + ~~~~~~ + + .. code-block:: python + + import simplnx as sx + + # Example File has 7 columns to import + read_csv_data = sx.ReadCSVDataParameter() + read_csv_data.input_file_path = "/tmp/test_csv_data.csv" + read_csv_data.start_import_row = 2 + read_csv_data.delimiters = [','] + read_csv_data.custom_headers = [] + read_csv_data.column_data_types = [sx.DataType.float32,sx.DataType.float32,sx.DataType.float32,sx.DataType.float32,sx.DataType.float32,sx.DataType.float32,sx.DataType.int32] + read_csv_data.skipped_array_mask = [False,False,False,False,False,False,False] + read_csv_data.tuple_dims = [37989] + read_csv_data.headers_line = 1 + read_csv_data.header_mode = sx.ReadCSVDataParameter.HeaderMode.Line + params.insert(sx.ReadCSVFileParameter('csv_importer_data_key', "CSV Importer Data", "Holds all relevant csv file data collected from the custom interface", read_csv_data)) + +.. _ReadH5EbsdFileParameter: +.. py:class:: ReadH5EbsdFileParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + class ReadH5EbsdFileParameter(simplnx.IParameter): + def __init__(self, name: str, human_name: str, help_text: str, default_value: ReadH5EbsdFileParameter.ValueType) -> None: ... + + Description + ~~~~~~~~~~~ + This parameter is used for the :ref:`orientationAnalysis.ReadH5EbsdFilter() ` and holds the information to import the EBSD data from the H5EBSD file. + + The primary python object that will hold the default information to pass to this parameter is the ReadH5EbsdFileParameter.ValueType class described below. + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : ReadH5EbsdFileParameter.ValueType + - **Description**: The default configuration for reading the EBSD data. + - **Type**: `ReadH5EbsdFileParameter.ValueType` + + ``ReadH5EbsdFileParameter.ValueType`` Class + ------------------------------------------- + Represents the configuration for reading EBSD data from the H5EBSD file. + + - **Fields**: + - ``end_slice`` : int + - **Description**: The end slice (inclusive) for the EBSD data import. + - ``euler_representation`` : int + - **Description**: The representation of Euler angles in the EBSD data. 0 = Radians, 1 = Degrees. + - ``input_file_path`` : str + - **Description**: The file path to the input .h5ebsd file containing EBSD data. + - ``selected_array_names`` : List[str] + - **Description**: The names of the EBSD data to import. These may differ slightly between the various OEMs. + - ``start_slice`` : int + - **Description**: The start slice for the EBSD data import. + - ``use_recommended_transform`` : bool + - **Description**: Apply the stored sample and crystal reference frame transformations. + + Usage + ~~~~~~ + + .. code-block:: python + + import orientationanalysis as oa + + read_h5ebsd_data = oa.ReadH5EbsdFileParameter.ValueType() + read_h5ebsd_data.euler_representation=0 + read_h5ebsd_data.end_slice=117 + read_h5ebsd_data.selected_array_names=["Confidence Index", "EulerAngles", "Fit", "Image Quality", "Phases", "SEM Signal", "X Position", "Y Position"] + read_h5ebsd_data.input_file_path="Data/Output/Reconstruction/Small_IN100.h5ebsd" + read_h5ebsd_data.start_slice=1 + read_h5ebsd_data.use_recommended_transform=True + params.insert(oa.ReadH5EbsdFileParameter('import_h5ebsd_file_key', "Import H5Ebsd File", "Object that holds all relevant information to import data from the file.", read_h5ebsd_data)) + +.. _ReadHDF5DatasetParameter: +.. py:class:: ReadHDF5DatasetParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + class ReadHDF5DatasetParameter(IParameter): + def __init__(self, name: str, human_name: str, help_text: str, default_value: ReadHDF5DatasetParameter.ValueType) -> None: ... + + Description + ~~~~~~~~~~~ + This parameter is used for the :ref:`simplnx.ReadHDF5Dataset` and holds the information to import specific data sets from within the HDF5 file into DREAM3D/simplnx + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : ReadHDF5DatasetParameter.ValueType + - **Description**: The default configuration for reading the data sets from the HDF5 file. + - **Type**: `ReadHDF5DatasetParameter.ValueType` + + ``ReadHDF5DatasetParameter.DatasetImportInfo`` Class + ---------------------------------------------------- + Represents the configuration for importing a single data set from the HDF5 file. + + - **Fields**: + - ``component_dims`` : str + - **Description**: The dimensions of the components in the data set. + - ``dataset_path`` : str + - **Description**: The path to the data set within the HDF5 file. + - ``tuple_dims`` : str + - **Description**: The dimensions of the tuples in the data set. + + ``ReadHDF5DatasetParameter.ValueType`` Class + -------------------------------------------- + Represents the configuration for importing data sets from the HDF5 file. + + - **Fields**: + - ``datasets`` : List[ReadHDF5DatasetParameter.DatasetImportInfo] + - **Description**: The list of data sets to be imported. + - ``input_file`` : str + - **Description**: The file path to the input HDF5 file. + - ``parent`` : Optional[DataPath] + - **Description**: The :ref:`DataPath ` object to a parent group to create the :ref:`DataArrays ` into. If left blank, the :ref:`DataArray ` will be created at the top level of the :ref:`DataStructure`. + + Usage + ~~~~~~ + + .. code-block:: python + + import simplnx as sx + + dataset1 = sx.ReadHDF5DatasetParameter.DatasetImportInfo() + dataset1.dataset_path = "/DataStructure/DataContainer/CellData/Confidence Index" + dataset1.tuple_dims = "117,201,189" + dataset1.component_dims = "1" + + dataset2 = sx.ReadHDF5DatasetParameter.DatasetImportInfo() + dataset2.dataset_path = "/DataStructure/DataContainer/CellData/EulerAngles" + dataset2.tuple_dims = "117,201,189" + dataset2.component_dims = "3" + + import_hdf5_param = sx.ReadHDF5DatasetParameter.ValueType() + import_hdf5_param.input_file = "SmallIN100_Final.dream3d" + import_hdf5_param.datasets = [dataset1, dataset2] + + params.insert(sx.ReadHDF5DatasetParameter('hdf5_file_key', "Select HDF5 File", "The HDF5 file data to import", import_hdf5_param)) + +.. _MultiArraySelectionParameter: +.. py:class:: MultiArraySelectionParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + class MultiArraySelectionParameter(IParameter): + def __init__(self, name: str, human_name: str, help_text: str, default_value: List[DataPath], allowed_types: Set[IArray.ArrayType], allowed_data_types: Set[DataType], required_comps: List[List[int]] = ...) -> None: ... + + Description + ~~~~~~~~~~~ + This parameter is used to specify a selection of multiple arrays within the data structure, constrained by component dimensions as well as allowed array and data types. + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : List[DataPath] + - **Description**: The default paths to the selected arrays. + - **Type**: List of `DataPath` + + - ``allowed_types`` : Set[IArray.ArrayType] + - **Description**: The set of allowed array types for the selected arrays. + - **Type**: Set of `IArray.ArrayType` + + - ``allowed_data_types`` : Set[DataType] + - **Description**: The set of allowed data types for the selected arrays. + - **Type**: Set of `DataType` + + - ``required_comps`` : List[List[int]] + - **Description**: List of required component dimensions for the selected arrays. + - **Type**: List of lists of integers + + Usage + ~~~~~~ + + .. code-block:: python + + import simplnx as sx + + params.insert(sx.MultiArraySelectionParameter(ExampleFilter2.PARAM12_KEY, 'MultiArraySelectionParameter', 'Example multiarray selection help text', [], set([sx.IArray.ArrayType.Any]), sx.get_all_data_types(), [[1]])) + + +.. _MultiPathSelectionParameter: +.. py:class:: MultiPathSelectionParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + class MultiPathSelectionParameter(IParameter): + def __init__(self, name: str, human_name: str, help_text: str, default_value: List[DataPath]) -> None: ... + + Description + ~~~~~~~~~~~ + This parameter represents a list of :ref:`DataPath ` objects. The end point of each :ref:`DataPath ` object can be any object in the :ref:`DataStructure` + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : List[DataPath] + - **Description**: The default paths selected by the parameter. + - **Type**: List of `DataPath` + + Usage + ~~~~~~ + + .. code-block:: python + + import simplnx as sx + + params.insert(sx.MultiPathSelectionParameter('objects_to_copy_key', "Objects to copy", "A list of DataPaths to the DataObjects to be copied", [sx.DataPath(["Small IN100", "Scan Data", "Confidence Index"]), sx.DataPath(["Small IN100", "Scan Data", "Euler Angles"])])) + +.. _NeighborListSelectionParameter: +.. py:class:: NeighborListSelectionParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + class NeighborListSelectionParameter(IParameter): + def __init__(self, name: str, human_name: str, help_text: str, default_value: DataPath, allowed_types: Set[DataType]) -> None: ... + + Description + ~~~~~~~~~~~ + The ``NeighborListSelectionParameter`` is used to specify a selection of a neighbor list array within the data structure, constrained by allowed data types. + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : DataPath + - **Description**: The default path to the neighbor list array. + - **Type**: `DataPath` + + - ``allowed_types`` : Set[DataType] + - **Description**: The set of allowed data types for the neighbor list. + - **Type**: Set of `DataType` + + Usage + ~~~~~~ + + .. code-block:: python + + import simplnx as sx + + params.insert(sx.NeighborListSelectionParameter('neighbor_list_key', "Neighbor List", "List of the contiguous neighboring Features for a given Feature", sx.DataPath([]), set([sx.DataType.int32]))) + +.. _NumericTypeParameter: +.. py:class:: NumericTypeParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + class NumericTypeParameter(IParameter): + def __init__(self, name: str, human_name: str, help_text: str, default_value: NumericType) -> None: ... + + Description + ~~~~~~~~~~~ + This parameter represents a choice from a list of known numeric types. The programmer should use the predefined types instead of a plain integer value. + + - NumericType.int8 = 0 + - NumericType.uint8= 1 + - NumericType.int16= 2 + - NumericType.uint16= 3 + - NumericType.int32= 4 + - NumericType.uint32= 5 + - NumericType.int64= 6 + - NumericType.uint64= 7 + - NumericType.float32= 8 + - NumericType.float64= 9 + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : NumericType + - **Description**: The default numeric type. + - **Type**: `NumericType` + + Usage + ~~~~~~ + + .. code-block:: python + + import simplnx as sx + + params.insert(sx.NumericTypeParameter('numeric_type_key', 'Numeric Type', 'Example numeric type help text', sx.NumericType.int32)) + +.. _StringParameter: +.. py:class:: StringParameter + + Declaration + ~~~~~~~~~~~ + .. code-block:: python + + class StringParameter(IParameter): + def __init__(self, name: str, human_name: str, help_text: str, default_value: str) -> None: ... + + Description + ~~~~~~~~~~~ + The ``StringParameter`` is used to specify a string input. + + Inputs + ~~~~~~ + - ``name`` : str + - **Description**: The programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : str + - **Description**: The default string value for the parameter. + - **Type**: string (str) + + Usage + ~~~~~~ + + .. code-block:: python + + import simplnx as sx + + params.insert(sx.StringParameter('string_key', 'StringParameter', 'Example string help text', 'Example String')) + +Numerical Parameters +-------------------- + +Declarations +~~~~~~~~~~~~ + + .. code-block:: python + + class Int8Parameter(IParameter): + def __init__(self, name: str, human_name: str, help_text: str, default_value: int) -> None: ... + + class UInt8Parameter(IParameter): + def __init__(self, name: str, human_name: str, help_text: str, default_value: int) -> None: ... + + class Int16Parameter(IParameter): + def __init__(self, name: str, human_name: str, help_text: str, default_value: int) -> None: ... + + class UInt16Parameter(IParameter): + def __init__(self, name: str, human_name: str, help_text: str, default_value: int) -> None: ... + + class Int32Parameter(IParameter): + def __init__(self, name: str, human_name: str, help_text: str, default_value: int) -> None: ... + + class UInt32Parameter(IParameter): + def __init__(self, name: str, human_name: str, help_text: str, default_value: int) -> None: ... + + class Int64Parameter(IParameter): + def __init__(self, name: str, human_name: str, help_text: str, default_value: int) -> None: ... + + class UInt64Parameter(IParameter): + def __init__(self, name: str, human_name: str, help_text: str, default_value: int) -> None: ... + + class Float32Parameter(IParameter): + def __init__(self, name: str, human_name: str, help_text: str, default_value: float) -> None: ... + + class Float64Parameter(IParameter): + def __init__(self, name: str, human_name: str, help_text: str, default_value: float) -> None: ... + +Description +~~~~~~~~~~~ + + This group of parameters wrap a specific native C++ numeric type and can be used to add integer/float inputs to a filter. Their default values can be instantiated using standard python integers or decimal values. + +Inputs +~~~~~~ + - ``name`` : str + - **Description**: The programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : int + - **Description**: The default value for the parameter, expected to be within the range of the chosen float or integer type. + - **Type**: Integer or Float + +Usage +~~~~~~ + + .. code-block:: python + + import simplnx as sx + + params.insert(sx.Float32Parameter('float32_key', 'Float32Parameter', 'The 1st parameter', 0.1234)) + params.insert(sx.Int32Parameter('int32_key', 'Int32Parameter', 'The 2nd parameter', 0)) + +Numerical Vector Parameters +--------------------------- + +Declarations +~~~~~~~~~~~~ + + .. code-block:: python + + class VectorInt8Parameter(IParameter): + @overload + def __init__(self, name: str, human_name: str, help_text: str, default_value: List[int]) -> None: ... + @overload + def __init__(self, name: str, human_name: str, help_text: str, default_value: List[int], names: List[str]) -> None: ... + + class VectorUInt8Parameter(IParameter): + @overload + def __init__(self, name: str, human_name: str, help_text: str, default_value: List[int]) -> None: ... + @overload + def __init__(self, name: str, human_name: str, help_text: str, default_value: List[int], names: List[str]) -> None: ... + + class VectorInt16Parameter(IParameter): + @overload + def __init__(self, name: str, human_name: str, help_text: str, default_value: List[int]) -> None: ... + @overload + def __init__(self, name: str, human_name: str, help_text: str, default_value: List[int], names: List[str]) -> None: ... + + class VectorUInt16Parameter(IParameter): + @overload + def __init__(self, name: str, human_name: str, help_text: str, default_value: List[int]) -> None: ... + @overload + def __init__(self, name: str, human_name: str, help_text: str, default_value: List[int], names: List[str]) -> None: ... + + class VectorInt32Parameter(IParameter): + @overload + def __init__(self, name: str, human_name: str, help_text: str, default_value: List[int]) -> None: ... + @overload + def __init__(self, name: str, human_name: str, help_text: str, default_value: List[int], names: List[str]) -> None: ... + + class VectorUInt32Parameter(IParameter): + @overload + def __init__(self, name: str, human_name: str, help_text: str, default_value: List[int]) -> None: ... + @overload + def __init__(self, name: str, human_name: str, help_text: str, default_value: List[int], names: List[str]) -> None: ... + + class VectorInt64Parameter(IParameter): + @overload + def __init__(self, name: str, human_name: str, help_text: str, default_value: List[int]) -> None: ... + @overload + def __init__(self, name: str, human_name: str, help_text: str, default_value: List[int], names: List[str]) -> None: ... + + class VectorUInt64Parameter(IParameter): + @overload + def __init__(self, name: str, human_name: str, help_text: str, default_value: List[int]) -> None: ... + @overload + def __init__(self, name: str, human_name: str, help_text: str, default_value: List[int], names: List[str]) -> None: ... + + class VectorFloat32Parameter(IParameter): + @overload + def __init__(self, name: str, human_name: str, help_text: str, default_value: List[float]) -> None: ... + @overload + def __init__(self, name: str, human_name: str, help_text: str, default_value: List[float], names: List[str]) -> None: ... + + class VectorFloat64Parameter(IParameter): + @overload + def __init__(self, name: str, human_name: str, help_text: str, default_value: List[float]) -> None: ... + @overload + def __init__(self, name: str, human_name: str, help_text: str, default_value: List[float], names: List[str]) -> None: ... + +Description +~~~~~~~~~~~ + + This group of parameters can be used to gather more than a single scalar value from the user. For example, an Origin for an Image Geometry or the dimensions of a DataArray. It is represented as a list of numerical values. + +Inputs +~~~~~~ + - ``name`` : str + - **Description**: The programmatic name of the parameter. + - **Type**: string (str) + + - ``human_name`` : str + - **Description**: The human-readable name of the parameter. + - **Type**: string (str) + + - ``help_text`` : str + - **Description**: A brief description or help text for the parameter. + - **Type**: string (str) + + - ``default_value`` : int + - **Description**: The default value for the parameter, a list of integers or floats that are all expected to be within the range of the chosen float or integer type. + - **Type**: List of Integers or Floats + + - ``names`` : int + - **Description**: The list of names that describe each value in the vector. + - **Type**: List of strings + +Usage +~~~~~~ + + .. code-block:: python + + import simplnx as sx + + params.insert(sx.VectorInt32Parameter('3d_dimensions_key', '3D Dimensions', 'Example int32 vector help text', [-19, -100, 456], ["X", "Y", "Z"])) + params.insert(sx.VectorFloat64Parameter('quaternion_key', 'Quaternion', 'Example float64 vector help text', [0, 84.98, 234.12, 985.98], ["U", "V", "W", "X"])) diff --git a/wrapping/python/docs/source/Images/Generate_Python_Plugin.png b/wrapping/python/docs/source/Images/Generate_Python_Plugin.png new file mode 100644 index 0000000000..3f43e9afc2 Binary files /dev/null and b/wrapping/python/docs/source/Images/Generate_Python_Plugin.png differ diff --git a/wrapping/python/docs/source/Images/Generate_Python_Plugin_2.png b/wrapping/python/docs/source/Images/Generate_Python_Plugin_2.png new file mode 100644 index 0000000000..9429ec53ff Binary files /dev/null and b/wrapping/python/docs/source/Images/Generate_Python_Plugin_2.png differ diff --git a/wrapping/python/docs/source/Python_Introduction.rst b/wrapping/python/docs/source/Python_Introduction.rst index 2489594514..2ba0928bd4 100644 --- a/wrapping/python/docs/source/Python_Introduction.rst +++ b/wrapping/python/docs/source/Python_Introduction.rst @@ -68,23 +68,44 @@ the :ref:`DataStructure`. Executing a simplnx filter can be done in one of two w can be useful if the developer would like to build up a list of filters and then execute them one after another. -An example of executing a file in immediate mode is the following code snippet. +An example of executing a file in immediate mode using a filter from the simplnx library: .. code:: python - result = cx.CreateDataArray.execute(data_structure=data_structure, + import simplnx as sx + + result = sx.CreateDataArray.execute(data_structure=data_structure, component_count=1, data_format="", initialization_value="10", - numeric_type=cx.NumericType.float32, - output_data_array=cx.DataPath(["3D Array"]), + numeric_type=sx.NumericType.float32, + output_data_array=sx.DataPath(["3D Array"]), tuple_dimensions= [[3, 2, 5]]) - npdata = data_structure[cx.DataPath(["3D Array"])].npview() - + npdata = data_structure[sx.DataPath(["3D Array"])].npview() The resulting :ref:`DataArray ` is available for use immediately following the execution of the filter. This would not be the case had the filter just been instantiated but not executed. +Executing Python filters directly from Python is similar, but has an additional line of code that is required. + +.. code:: python + + from ExamplePlugin import ExampleFilter2 + f = sx.PyFilter(ExampleFilter2()) + +This code wraps the Python filter ExampleFilter2 into a PyFilter instance so that it can be executed by *simplnx*. Here is the full example of executing the Python filter **ExampleFilter2** from plugin **ExamplePlugin** in immediate mode: + +.. code:: python + + from ExamplePlugin import ExampleFilter2 + + f = sx.PyFilter(ExampleFilter2()) + ds = sx.DataStructure() + result = f.preflight2(ds) + result = f.execute2(ds) + +In this way, developers can execute Python filters from Python. This can be useful if the developer needs to debug their Python filter and see variables. + Creating a DataGroup -------------------- diff --git a/wrapping/python/docs/source/ReleaseNotes_110.rst b/wrapping/python/docs/source/ReleaseNotes_110.rst index b8b0ba6d39..b71ceb1a2e 100644 --- a/wrapping/python/docs/source/ReleaseNotes_110.rst +++ b/wrapping/python/docs/source/ReleaseNotes_110.rst @@ -10,7 +10,7 @@ Version 1.1.0 API Additions 1.1.0 ^^^^^^^^^^^^^^^^^^^ -- DataPath: A :ref:`DataPath` object can now be constructed with a "/" separated string in addition to a list of strings. +- DataPath: A :ref:`DataPath ` object can now be constructed with a "/" separated string in addition to a list of strings. .. code:: python diff --git a/wrapping/python/docs/source/API.rst b/wrapping/python/docs/source/User_API.rst similarity index 92% rename from wrapping/python/docs/source/API.rst rename to wrapping/python/docs/source/User_API.rst index 5df5292e74..8fabb5f3e7 100644 --- a/wrapping/python/docs/source/API.rst +++ b/wrapping/python/docs/source/User_API.rst @@ -1,5 +1,8 @@ -Filter Parameter Classes -======================== +API for Users +============== + +Error & Warning Reporting +-------------------------- .. _Result: .. py:class:: Result @@ -26,7 +29,8 @@ General Parameters .. _ArrayCreationParameter: .. py:class:: ArrayCreationParameter - This parameter holds a :ref:`DataPath` value that points to the location within the DataStructure of where + + This parameter holds a :ref:`DataPath ` value that points to the location within the DataStructure of where the DataArray will be created. .. code:: python @@ -36,7 +40,7 @@ General Parameters .. _ArraySelectionParameter: .. py:class:: ArraySelectionParameter - This parameter holds a :ref:`DataPath` value that points to the location within the DataStructure of where + This parameter holds a :ref:`DataPath ` value that points to the location within the DataStructure of where the DataArray will be read. .. code:: python @@ -62,7 +66,7 @@ General Parameters This class holds the values that are used for comparison in the :ref:`simplnx.MultiThresholdObjects() ` filter. - :ivar array_path: The :ref:`DataPath` to the array to use for this ArrayThreshold + :ivar array_path: The :ref:`DataPath ` to the array to use for this ArrayThreshold :ivar comparison: Int. The comparison operator to use. 0=">", 1="<", 2="=", 3="!=" :ivar value: Numerical Value. The value for the comparison @@ -92,7 +96,7 @@ General Parameters .. _AttributeMatrixSelectionParameter: .. py:class:: AttributeMatrixSelectionParameter - This parameter holds a :ref:`DataPath` value that points to the location within the DataStructure of a selected AttributeMatrix. + This parameter holds a :ref:`DataPath ` value that points to the location within the DataStructure of a selected AttributeMatrix. .. code:: python @@ -114,7 +118,7 @@ General Parameters .. py:class:: CalculatorParameter.ValueType - :ivar selected_group: The :ref:`DataGroup` or :ref:`AttributeMatrix` that contains the :ref:`DataArray` that will be used in the equations + :ivar selected_group: The :ref:`DataGroup` or :ref:`AttributeMatrix` that contains the :ref:`DataArray ` that will be used in the equations :ivar equation: String. The equation that will be evaluated :ivar units: cx.CalculatorParameter.AngleUnits.Radians or cx.CalculatorParameter.AngleUnits.Degrees @@ -144,7 +148,7 @@ General Parameters .. _DataGroupCreationParameter: .. py:class:: DataGroupCreationParameter - This parameter holds a :ref:`DataPath` value that points to the location within the DataStructure of a :ref:`DataGroup` that will be created + This parameter holds a :ref:`DataPath ` value that points to the location within the DataStructure of a :ref:`DataGroup` that will be created by the filter. .. code:: python @@ -154,7 +158,7 @@ General Parameters .. _DataGroupSelectionParameter: .. py:class:: DataGroupSelectionParameter - This parameter holds a :ref:`DataPath` value that points to the location within the DataStructure of a :ref:`DataGroup` that will be used in the filter. + This parameter holds a :ref:`DataPath ` value that points to the location within the DataStructure of a :ref:`DataGroup` that will be used in the filter. .. code:: python @@ -172,7 +176,7 @@ General Parameters .. _DataPathSelectionParameter: .. py:class:: DataPathSelectionParameter - This parameter holds a :ref:`DataPath` object that represents an object within the :ref:`DataStructure`. + This parameter holds a :ref:`DataPath ` object that represents an object within the :ref:`DataStructure`. .. code:: python @@ -217,7 +221,7 @@ General Parameters The ImportData object has 2 member variables that can be set. :ivar file_path: Path to the .dream3d file on the file system - :ivar data_paths: List of :ref:`DataPath` objects. Use the python 'None' value to indicate that you want to read **ALL** the data from file. + :ivar data_paths: List of :ref:`DataPath ` objects. Use the python 'None' value to indicate that you want to read **ALL** the data from file. .. code:: python @@ -381,7 +385,7 @@ General Parameters .. _GeometrySelectionParameter: .. py:class:: GeometrySelectionParameter - This parameter represents the :ref:`DataPath` to a valid :ref:`simplnx.Geometry() ` + This parameter represents the :ref:`DataPath ` to a valid :ref:`simplnx.Geometry() ` .. _ReadCSVDataParameter: .. py:class:: ReadCSVDataParameter @@ -408,8 +412,8 @@ General Parameters :ivar start_import_row: Int. What line number does the data start on. ONE (1) Based numbering scheme. :ivar delimiters: List[string]. List of delimiters that will be used to separate the lines of the file into columns. :ivar consecutive_delimiters: Bool. Should consecutive delimiters be counted as a single delimiter. - :ivar custom_headers: List[string]. If the file does not have headers, this is a list of string values, 1 per column of data, that will also become the names of the created :ref:`DataArray`. - :ivar data_types: List[:ref:`cx.DataType`]. The DataType, one per column, that indicates the kind of native numerical values (int, float... ) that will be used in the created :ref:`DataArray`. + :ivar custom_headers: List[string]. If the file does not have headers, this is a list of string values, 1 per column of data, that will also become the names of the created :ref:`DataArray `. + :ivar data_types: List[:ref:`cx.DataType`]. The DataType, one per column, that indicates the kind of native numerical values (int, float... ) that will be used in the created :ref:`DataArray `. :ivar skipped_array_mask: List[bool]. Booleans, one per column, that indicate whether or not to skip importing each created :ref:`DataArray `. :ivar tuple_dims: List[int]. The tuple dimensions for the created :ref:`DataArrays `. :ivar headers_line: Int. The line number of the file that has the headers listed on a single line. ONE (1) based indexing. @@ -498,7 +502,7 @@ General Parameters :ivar input_file: A "PathLike" value to the HDF5 file on the file system :ivar datasets: list[ReadHDF5DatasetParameter.DatasetImportInfo, ....] - :ivar parent: Optional: The :ref:`DataPath` object to a parente group to create the :ref:`DataArray` into. If left blank the :ref:`DataArray` will be created at the top level of the :ref:`DataStructure` + :ivar parent: Optional: The :ref:`DataPath ` object to a parente group to create the :ref:`DataArray ` into. If left blank the :ref:`DataArray ` will be created at the top level of the :ref:`DataStructure` .. py:class:: ReadHDF5DatasetParameter.DatasetImportInfo @@ -533,8 +537,8 @@ General Parameters .. _MultiArraySelectionParameter: .. py:class:: MultiArraySelectionParameter - This parameter represents a list of :ref:`DataPath` objects where each :ref:`DataPath` object - points to a :ref:`DataArray` + This parameter represents a list of :ref:`DataPath ` objects where each :ref:`DataPath ` object + points to a :ref:`DataArray ` .. code:: python @@ -543,7 +547,7 @@ General Parameters .. _MultiPathSelectionParameter: .. py:class:: MultiPathSelectionParameter - This parameter represents a list of :ref:`DataPath` objects. The end point of each :ref:`DataPath` + This parameter represents a list of :ref:`DataPath ` objects. The end point of each :ref:`DataPath ` object can be any object in the :ref:`DataStructure` .. code:: python @@ -554,7 +558,7 @@ General Parameters .. _NeighborListSelectionParameter: .. py:class:: NeighborListSelectionParameter - This parameter represents a :ref:`DataPath` object that has an end point of a 'cx.NeighborList' object + This parameter represents a :ref:`DataPath ` object that has an end point of a 'cx.NeighborList' object .. _NumericTypeParameter: .. py:class:: NumericTypeParameter diff --git a/wrapping/python/docs/source/Writing_A_New_Python_Filter.rst b/wrapping/python/docs/source/Writing_A_New_Python_Filter.rst new file mode 100644 index 0000000000..4960ea8051 --- /dev/null +++ b/wrapping/python/docs/source/Writing_A_New_Python_Filter.rst @@ -0,0 +1,403 @@ +Writing a New Python Filter +=========================== + +0. Environment Setup +-------------------- + +You will need to first setup your python environment. We will be using an Anaconda virtual environment for this tutorial. + +.. 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 dream3dnx + +Or, if you are installing from a local conda-bld directory, it will be something like: + +.. code:: shell + + conda install -c file:///some/path/to/a/conda-build/folder dream3dnx + + +Wait until the environment is fully installed. + +- Next you will want to launch **DREAM3D-NX** from the same Anaconda command prompt. + + **MacOS** + + .. code:: shell + + $(conda info --envs | grep '*' | awk '{print $3}')/bin/DREAM3DNX.app/Contents/MacOS/DREAM3DNX + + **Linux** + + .. code:: shell + + dream3dnx + + **Windows** + + .. code:: shell + + dream3dnx.exe + +1. Generating the Skeleton Code +------------------------------- + +**Generate Python Plugin and/or Python Filters** is a filter in *simplnx* that generates the skeleton code for new Python filters. + +This filter can generate skeleton code for the new filters in an existing Python plugin, or it can also generate the skeleton code for a new Python plugin. + +**Steps:** + +#. **Access the Filter:** + - Add the **Generate Python Plugin and/or Python Filters** filter to your pipeline. + +#. **Configure the Filter:** + **New Python Plugin** + .. image:: Images/Generate_Python_Plugin.png + + - Turn OFF *Use Existing Plugin*. + - Input the programmatic name and human name for the new plugin. + - Select the output directory for the new plugin. + - Set the desired programmatic names for your new filters (separated by commas). + + **Existing Python Plugin** + .. image:: Images/Generate_Python_Plugin_2.png + + - Turn ON *Use Existing Plugin*. + - Select the existing plugin location on the file system (the top-level directory of the existing plugin). + - Set the desired programmatic names for your new filters (separated by commas). + +#. **Generate the Code:** + #. Run the filter. + - If *Use Existing Plugin* is OFF, then the new plugin directory structure and new filters will be generated at the specified output directory. + - If *Use Existing Plugin* is ON, then the new filters will be generated inside the existing plugin at the specified location. + +2. Loading The New Plugin +------------------------- +After you have generated your Python plugin/filters, close the current instance of DREAM3D-NX. Now, from the same Anaconda command prompt as before: + +- Export the `PYTHONPATH` environment variable and have that point to a folder that you will be saving your new plugin into or a folder that holds your currently in-development plugin. Set the `SIMPLNX_PYTHON_PLUGINS` environment variable to the name of your plugin. Multiple plugin names should be separated by commas. + + **MacOS/Linux** + + .. code:: shell + + export PYTHONPATH=/path/to/plugin/parent/directory + export SIMPLNX_PYTHON_PLUGINS=[NAME_OF_PLUGIN] + + **Windows** + + .. code:: shell + + set PYTHONPATH=/path/to/plugin/parent/directory + set SIMPLNX_PYTHON_PLUGINS=[NAME_OF_PLUGIN] + +- Re-launch **DREAM3D-NX** again. + + **MacOS** + + .. code:: shell + + $(conda info --envs | grep '*' | awk '{print $3}')/bin/DREAM3DNX.app/Contents/MacOS/DREAM3DNX + + **Linux** + + .. code:: shell + + dream3dnx + + **Windows** + + .. code:: shell + + dream3dnx.exe + +You should now see your new filters loaded in the DREAM3D-NX user interface. Search for your filter's name in the Filter List to verify. + +3. Understanding the Plugin Structure +------------------------------------- + +Python plugins in *simplnx* contain 2 main files (**__init__.py** and **Plugin.py**) and the filter files. + +- **__init__.py:** The plugin initialization module that determines which symbols are to be exported when `from PLUGIN_NAME import *` is used. Also includes a `get_plugin` method that returns an instance of the plugin (used during the process of discovering and loading Python plugins). + +- **Plugin.py:** The main plugin module that contains the plugin's unique id, plugin name, plugin description, plugin's vendor, and the list of filters available in the plugin. + +- **Filter Files:** The Python modules that contain the parameter setup, validation, and execution logic for each filter. + +4. Understanding the Filter Skeleton Structure +---------------------------------------------- + +The skeleton provides a basic structure with placeholders and conventions that align with *simplnx*'s architecture. + +**Components:** + +- **Filter Class:** The main class that represents your filter. + + .. code-block:: python + + class FirstFilter: + # Filter class definition + +- **Parameter Keys:** Use descriptive constants to define keys for your parameters. These keys will be used to access parameter values from the `args` dictionary in `preflight_impl` and `execute_impl`. + + .. code-block:: python + + """ + This section should contain the 'keys' that store each parameter. The value of the key should be snake_case. The name of the value should be ALL_CAPITOL_KEY + """ + TEST_KEY = 'test' + +- **UUID Method:** This method returns the unique identifier for the new filter. This unique identifier is automatically generated and should typically not be modified. + + **NOTE:** If you are creating a new filter by copying the contents of an existing filter file (NOT generating a new filter), this unique identifier MUST be modified! For this case, you can simply call `uuidgen` from the command line and then copy the result into this method. + + .. code-block:: python + + def uuid(self) -> nx.Uuid: + """This returns the UUID of the filter. Each filter has a unique UUID value + :return: The Filter's Uuid value + :rtype: string + """ + return nx.Uuid('caad34b3-54e3-4276-962e-b59cd88b7320') + +- **Human Name Method:** This method returns the human-readable name for the filter. This name is typically used in the DREAM3D-NX GUI. It is set, by default, to the programmatic name of the filter and should probably be modified to something more human-readable. + + .. code-block:: python + + def human_name(self) -> str: + """This returns the name of the filter as a user of DREAM3DNX would see it + :return: The filter's human name + :rtype: string + """ + return 'FirstFilter' # This could be updated to return 'First Filter' or '1st Filter', or any other human-readable name. + +- **Class Name Method:** This method returns the programmatic name for the filter. + + .. code-block:: python + + def class_name(self) -> str: + """The returns the name of the class that implements the filter + :return: The name of the implementation class + :rtype: string + """ + return 'FirstFilter' + +- **Name Method:** This method returns a generic name for the filter. + + .. code-block:: python + + def name(self) -> str: + """The returns the name of filter + :return: The name of the filter + :rtype: string + """ + return 'FirstFilter' + +- **Default Tags Method:** This method returns all the tags that are used to match this filter when searching. For example if this filter has the tag *Foo*, then any time *Foo* is searched in the Filter List, this filter will match and appear in the search results. The default tag for Python filters is *python*, but feel free to add more if needed. + + .. code-block:: python + + def default_tags(self) -> List[str]: + """This returns the default tags for this filter + :return: The default tags for the filter + :rtype: list + """ + return ['python'] + +- **Clone Method:** This method returns a new instance of the filter. This method should not be modified. + + .. code-block:: python + + def clone(self): + """Clones the filter + :return: A new instance of the filter + :rtype: FirstFilter + """ + return FirstFilter() + +- **Parameters Method:** Add *simplnx* filter parameters to this method to configure what inputs are available to users of the filter. + + .. code-block:: python + + def parameters(self) -> nx.Parameters: + params = nx.Parameters() + + # Add your parameters here + + return params + +- **Preflight and Execute Methods:** These are crucial methods where your filter's logic will reside. + + .. code-block:: python + + def preflight_impl(self, data_structure: nx.DataStructure, args: dict, message_handler: nx.IFilter.MessageHandler, should_cancel: nx.AtomicBoolProxy) -> nx.IFilter.PreflightResult: + # Preflight logic + + def execute_impl(self, data_structure: nx.DataStructure, args: dict, message_handler: nx.IFilter.MessageHandler, should_cancel: nx.AtomicBoolProxy) -> nx.IFilter.ExecuteResult: + # Execution logic + +5. Defining Parameters +---------------------- +Parameters determine what inputs are available to users; they make your filter configurable and adaptable to different datasets and scenarios. + +1. **Define Parameter Keys:** + - Use descriptive constants to define keys for your parameters. These keys will be used to access parameter values from the `args` dictionary in `preflight_impl` and `execute_impl`. + + .. code-block:: python + + OUTPUT_ARRAY_PATH = 'output_array_path_key' + INIT_VALUE_KEY = 'init_value_key' + NUM_TUPLES_KEY = 'num_tuples_key' + NUM_COMPS_KEY = 'num_comps_key' + +2. **Implement the `parameters` Method:** + - Create instances of parameter classes provided by *simplnx* and add them to your filter. + + .. code-block:: python + + def parameters(self): + params = nx.Parameters() + + # Create a 'Number of Tuples' input, where the filter's user can input an unsigned 64-bit integer + params.insert(nx.UInt64Parameter(FirstFilter.NUM_TUPLES_KEY, 'Number of Tuples', 'Number of Tuples', 1)) + + # Create a 'Number of Components' input, where the filter's user can input an unsigned 64-bit integer + params.insert(nx.UInt64Parameter(FirstFilter.NUM_COMPS_KEY, 'Number of Components', 'Number of Components', 1)) + + # Create an 'Initialization Value' input, where the filter's user can input the value that will be used to initialize the output array + params.insert(nx.Float32Parameter(FirstFilter.INIT_VALUE_KEY, 'Initialization Value', 'This value will be used to fill the new array', '0.0')) + + # Create the input that allows the filter's user to pick the path where the output array will be stored in the data structure + default_output_data_path = nx.DataPath(["Small IN100", "Scan Data", "Output"]) + params.insert(nx.ArrayCreationParameter(FirstFilter.OUTPUT_ARRAY_PATH, 'Array Creation', 'Example array creation help text', default_output_data_path)) + + return params + + For the full list of parameters and their arguments, please see `Developer_API `__. + + To see examples of how to instantiate each parameter, check out `ExampleFilter1 `__ and `ExampleFilter2 `__. + +6. Writing the Preflight Implementation +--------------------------------------- +The `preflight_impl` method allows you to perform checks, validations, and setup tasks before the filter's main execution. There are a number of basic steps that are performed but each +step could have any number of details associated to it. **The Preflight method should not be I/O or calculation intensive as it will be run every time a parameter in this filter or +any other filter is modified.** + +- Extract the input parameters values into local variables. +- Test those values for any non-allowed values, ranges or other conditions +- Use 'Actions' to modify the DataStructure as needed. These can be Array or Geometry creation or deletion. + +Each Parameter will do some basic kinds of sanity checks before the code execution ever makes it to your filter's 'preflight' method. For instance, 'File Input' parameters will already +ensure that the file exists on the file system so the developer does not need to redo this kind of validation. DataArray/GeometrySelection types of parameters will ensure +that the DataStructure DataPath already exists as another example. The filter parameter section will review the kinds of checks that each parameter perform + +**Example Preflight Method:** + This example creates a new 32-bit float output array using the number of tuples, number of components, and output array path provided by the user. It also validates that the initialization value is not set to 0. + + .. code-block:: python + + def preflight_impl(self, data_structure: nx.DataStructure, args: dict, message_handler: nx.IFilter.MessageHandler, should_cancel: nx.AtomicBoolProxy) -> nx.IFilter.PreflightResult: + # Retrieve the filter parameter values from the args dictionary using the filter's parameter keys + num_of_tuples: int = args[FirstFilter.NUM_TUPLES_KEY] + num_of_components: int = args[FirstFilter.NUM_COMPS_KEY] + init_value: float = args[FirstFilter.INIT_VALUE_KEY] + output_array_path: nx.DataPath = args[FirstFilter.OUTPUT_ARRAY_PATH] + + # Return a preflight error if the init value is 0 + if init_value == '0.0': + return nx.IFilter.PreflightResult(errors=[nx.Error(-123, 'Init Value cannot be 0.')]) + + # Create the new output array. This is done via a CreateArrayAction, which we will create and then append to the output actions. + # This will create the new output array and add it to the data structure so that it can be used later in the "execute_impl" method. + output_actions = nx.OutputActions() + output_actions.append_action(nx.CreateArrayAction(nx.DataType.float32, [num_of_tuples], [num_of_components], output_array_path)) + + # Return the output actions + return nx.IFilter.PreflightResult(output_actions) + +**Examples of the Major Steps:** + +- **Parameter Retrieval and Validation:** + - Extract and validate the parameters to ensure they meet your filter's requirements. + + .. code-block:: python + + init_value: float = args[FirstFilter.INIT_VALUE_KEY] + if init_value == '0.0': + return nx.IFilter.PreflightResult(errors=[nx.Error(-123, 'Init Value cannot be 0.')]) + +- **Output Actions Setup:** + - If your filter creates new data arrays, create and add the CreateArrayActions to the `output_actions` object. + + .. code-block:: python + + output_actions = nx.OutputActions() + output_actions.append_action(nx.CreateArrayAction(nx.DataType.float32, [num_of_tuples], [num_of_components], output_array_path)) + +8. Writing the Execute Implementation +------------------------------------- + +The `execute_impl` method holds the core functionality of the filter. This function is generally where the actual calculations are +performed. + +**Example Execute Method:** + This example sets the initialization value provided by the user into every index of the newly created output array. + + .. code-block:: python + + def execute_impl(self, data_structure: nx.DataStructure, args: dict, message_handler: nx.IFilter.MessageHandler, should_cancel: nx.AtomicBoolProxy) -> nx.IFilter.ExecuteResult: + # Retrieve the needed filter parameter values from the args dictionary using the filter's parameter keys + init_value: float = args[FirstFilter.INIT_VALUE_KEY] + output_array_path: nx.DataPath = args[FirstFilter.OUTPUT_ARRAY_PATH] + + # Get a reference to the output data array from the data structure + output_data_array: nx.IDataArray = data_structure[output_array_path] + + # Get a numpy view of the output data array + data = data_array.npview() + + # Set the init value into every index of the array + data[:] = init_value + + return nx.Result() + +**Key Aspects:** + +- **Parameter Retrieval:** + - Extract the necessary parameters from the args dictionary. + + .. code-block:: python + + # Retrieve the needed filter parameter values from the args dictionary using the filter's parameter keys + init_value: float = args[FirstFilter.INIT_VALUE_KEY] + output_array_path: nx.DataPath = args[FirstFilter.OUTPUT_ARRAY_PATH] + +- **Access Data Arrays/Objects From The Data Structure:** + - Use DataPaths to get a reference to data arrays and other data objects from the data structure. + + .. code-block:: python + + # Get a reference to the output data array from the data structure + output_data_array: nx.IDataArray = data_structure[output_array_path] + +- **Manipulating Data Arrays With Numpy:** + - Get a numpy view into data arrays and then set values into the arrays using numpy. + + .. code-block:: python + + # Get a numpy view of the output data array + data = data_array.npview() + + # Set the init value into every index of the array + data[:] = init_value + +Conclusion +---------- +By following this guide, you can create a custom Python filter for *simplnx* that is configurable, follows best practices, and integrates smoothly into data processing pipelines. Remember to thoroughly test your filter with different parameter configurations and datasets to ensure its robustness and correctness. + +For more Python filter examples, check out the `ExamplePlugin `_. \ No newline at end of file diff --git a/wrapping/python/docs/source/conf.py b/wrapping/python/docs/source/conf.py index d663a5cd56..a116902deb 100644 --- a/wrapping/python/docs/source/conf.py +++ b/wrapping/python/docs/source/conf.py @@ -23,7 +23,7 @@ templates_path = ['_templates'] exclude_patterns = [] - +suppress_warnings = ['autosectionlabel.*'] # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output diff --git a/wrapping/python/plugins/TestPlugin/CreateArray.py b/wrapping/python/plugins/ExamplePlugin/CreateArray.py similarity index 99% rename from wrapping/python/plugins/TestPlugin/CreateArray.py rename to wrapping/python/plugins/ExamplePlugin/CreateArray.py index e1cfc4aebd..d16ed1e416 100644 --- a/wrapping/python/plugins/TestPlugin/CreateArray.py +++ b/wrapping/python/plugins/ExamplePlugin/CreateArray.py @@ -21,7 +21,7 @@ def uuid(self) -> nx.Uuid: return nx.Uuid('14c4ab0e-f7fd-464e-a54b-013346506351') def human_name(self) -> str: - return 'CreateArrayFilter (Python)' + return 'Create Data Array (Python)' def class_name(self) -> str: return 'CreateArrayFilter' diff --git a/wrapping/python/plugins/ExamplePlugin/ExampleFilter1.py b/wrapping/python/plugins/ExamplePlugin/ExampleFilter1.py new file mode 100644 index 0000000000..486e7da716 --- /dev/null +++ b/wrapping/python/plugins/ExamplePlugin/ExampleFilter1.py @@ -0,0 +1,247 @@ +from typing import List +import simplnx as sx +import orientationanalysis as oa + +class ExampleFilter1: + """ + This section should contain the 'keys' that store each parameter. The value of the key should be snake_case. The name + of the value should be ALL_CAPITOL_KEY + """ + INPUT_DIR_KEY = 'input_dir' + INPUT_FILE_KEY = 'input_file' + OUTPUT_DIR_KEY = 'output_dir' + OUTPUT_FILE_KEY = 'output_file' + PARAM1_KEY = "param1" + PARAM2_KEY = "param2" + PARAM3_KEY = "param3" + PARAM4_KEY = "param4" + PARAM5_KEY = "param5" + PARAM6_KEY = "param6" + PARAM7_KEY = "param7" + PARAM8_KEY = "param8" + PARAM9_KEY = "param9" + PARAM10_KEY = "param10" + PARAM11_KEY = "param11" + PARAM12_KEY = "param12" + PARAM13_KEY = "param13" + PARAM14_KEY = "param14" + PARAM15_KEY = "param15" + PARAM16_KEY = 'param16' + PARAM17_KEY = 'param17' + PARAM18_KEY = 'param18' + PARAM19_KEY = 'param19' + PARAM20_KEY = 'param20' + VEC2_KEY = 'vec2_key' + VEC3_KEY = 'vec3_key' + VEC4_KEY = 'vec4_key' + VEC4F_KEY = 'vec4f_key' + VEC6F_KEY = 'vec6f_key' + + def uuid(self) -> sx.Uuid: + """This returns the UUID of the filter. Each filter has a unique UUID value + :return: The Filter's Uuid value + :rtype: string + """ + return sx.Uuid('33549513-69d9-441b-bfc1-2744977a1c61') + + def human_name(self) -> str: + """This returns the name of the filter as a user of DREAM3DNX would see it + :return: The filter's human name + :rtype: string + """ + return 'Example Filter 1 (Python)' + + def class_name(self) -> str: + """The returns the name of the class that implements the filter + :return: The name of the implementation class + :rtype: string + """ + return 'ExampleFilter1' + + def name(self) -> str: + """The returns the name of filter + :return: The name of the filter + :rtype: string + """ + return 'ExampleFilter1' + + def default_tags(self) -> List[str]: + """This returns the default tags for this filter + :return: The default tags for the filter + :rtype: list + """ + return ['python'] + + def clone(self): + """Clones the filter + :return: A new instance of the filter + :rtype: ExampleFilter1 + """ + return ExampleFilter1() + + def parameters(self) -> sx.Parameters: + """This function defines the parameters that are needed by the filter. Parameters collect the values from the user + or through a pipeline file. + """ + params = sx.Parameters() + + params.insert(sx.Parameters.Separator("FileSystem Selections")) + params.insert(sx.FileSystemPathParameter(ExampleFilter1.INPUT_DIR_KEY, 'Input Directory', 'Example input directory help text', 'Data', set(), sx.FileSystemPathParameter.PathType.InputDir)) + params.insert(sx.FileSystemPathParameter(ExampleFilter1.INPUT_FILE_KEY, 'Input File', 'Example input file help text', '/opt/local/bin/ninja', set(), sx.FileSystemPathParameter.PathType.InputFile, True)) + params.insert(sx.FileSystemPathParameter(ExampleFilter1.OUTPUT_DIR_KEY, 'Output Directory', 'Example output directory help text', 'Output Data', set(), sx.FileSystemPathParameter.PathType.OutputDir)) + params.insert(sx.FileSystemPathParameter(ExampleFilter1.OUTPUT_FILE_KEY, 'Output File', 'Example output file help text', '', set(), sx.FileSystemPathParameter.PathType.OutputFile)) + + params.insert(sx.Parameters.Separator("Linked Parameter")) + params.insert_linkable_parameter(sx.BoolParameter(ExampleFilter1.PARAM2_KEY, 'BoolParameter', 'The 2nd parameter', True)) + params.insert(sx.Float32Parameter(ExampleFilter1.PARAM1_KEY, 'Float32Parameter', 'The 1st parameter', 0.1234)) + params.insert(sx.Int32Parameter(ExampleFilter1.PARAM3_KEY, 'Int32Parameter', 'The 3rd parameter', 0)) + params.link_parameters(ExampleFilter1.PARAM2_KEY, ExampleFilter1.PARAM1_KEY, True) + + params.insert(sx.Parameters.Separator("Vector Parameters")) + params.insert(sx.VectorInt32Parameter(ExampleFilter1.VEC2_KEY, 'Vect', 'Example int32 vector help text', [10, 20], ["X", "Y"])) + params.insert(sx.VectorInt32Parameter(ExampleFilter1.VEC3_KEY, '3D Dimensions', 'Example int32 vector help text', [-19, -100, 456], ["X", "Y", "Z"])) + params.insert(sx.VectorUInt8Parameter(ExampleFilter1.VEC4_KEY, 'RGBA', 'Example uint8 vector help text', [0, 255, 128, 255], ["R", "G", "B", "A"])) + params.insert(sx.VectorFloat32Parameter(ExampleFilter1.VEC4F_KEY, 'Quaternion', 'Example float32 vector help text', [0, 84.98, 234.12, 985.98], ["U", "V", "W", "X"])) + + params.insert(sx.Parameters.Separator("Other Parameters")) + params.insert(sx.StringParameter(ExampleFilter1.PARAM5_KEY, 'StringParameter', 'Example string help text', 'Test String')) + params.insert(sx.DataObjectNameParameter(ExampleFilter1.PARAM11_KEY, 'DataObjectNameParameter', 'Example help text for DataObjectNameParameter', 'Data Group')) + params.insert(sx.NumericTypeParameter(ExampleFilter1.PARAM6_KEY, 'Numeric Type', 'Example numeric type help text', sx.NumericType.int32)) + params.insert(sx.DataTypeParameter(ExampleFilter1.PARAM13_KEY, "Data Type", "Example data type help text", sx.DataType.float64)) + params.insert(sx.DataStoreFormatParameter(ExampleFilter1.PARAM12_KEY, 'Data Store Format', 'This value will specify which data format is used by the array\'s data store. An empty string results in in-memory data store.', "")) + + import_data = sx.Dream3dImportParameter.ImportData() + import_data.file_path = "/private/tmp/basic_ebsd.dream3d" + import_data.data_paths = None + params.insert(sx.Dream3dImportParameter(ExampleFilter1.PARAM14_KEY, "Import File Path", "The HDF5 file path the DataStructure should be imported from.", import_data)) + + ensemble_info = [] + ensemble_info.append(["Hexagonal-High 6/mmm","Primary","Phase 1"]) + ensemble_info.append(["Cubic-High m-3m","Primary","Phase 2"]) + params.insert(sx.EnsembleInfoParameter(ExampleFilter1.PARAM15_KEY, "Created Ensemble Info", "The values with which to populate the crystal structures, phase types, and phase names data arrays. Each row corresponds to an ensemble phase.", ensemble_info)) + + color_control_points = sx.Json('{"RGBPoints": [0,0,0,0,0.4,0.901960784314,0,0,0.8,0.901960784314,0.901960784314,0,1,1,1,1]}') + params.insert(sx.GenerateColorTableParameter(ExampleFilter1.PARAM16_KEY, "Select Preset...", "Select a preset color scheme to apply to the created array", color_control_points)) + + dataset1 = sx.ReadHDF5DatasetParameter.DatasetImportInfo() + dataset1.dataset_path = "/DataStructure/DataContainer/CellData/Confidence Index" + dataset1.tuple_dims = "117,201,189" + dataset1.component_dims = "1" + dataset2 = sx.ReadHDF5DatasetParameter.DatasetImportInfo() + dataset2.dataset_path = "/DataStructure/DataContainer/CellData/EulerAngles" + dataset2.tuple_dims = "117,201,189" + dataset2.component_dims = "3" + import_hdf5_param = sx.ReadHDF5DatasetParameter.ValueType() + import_hdf5_param.input_file = "SmallIN100_Final.dream3d" + import_hdf5_param.datasets = [dataset1, dataset2] + params.insert(sx.ReadHDF5DatasetParameter(ExampleFilter1.PARAM20_KEY, "Select HDF5 File", "The HDF5 file data to import", import_hdf5_param)) + + params.insert(sx.Parameters.Separator("Generated File List Parameter")) + generated_file_list_value = sx.GeneratedFileListParameter.ValueType() + generated_file_list_value.input_path = "DREAM3DNXData/Data/Porosity_Image" + generated_file_list_value.ordering = sx.GeneratedFileListParameter.Ordering.LowToHigh + generated_file_list_value.file_prefix = "slice-" + generated_file_list_value.file_suffix = "" + generated_file_list_value.file_extension = ".tif" + generated_file_list_value.start_index = 11 + generated_file_list_value.end_index = 174 + generated_file_list_value.increment_index = 1 + generated_file_list_value.padding_digits = 2 + params.insert(sx.GeneratedFileListParameter(ExampleFilter1.PARAM17_KEY, "Input File List", "The list of files to be read", generated_file_list_value)) + + params.insert(sx.Parameters.Separator("Read CSV File Parameter")) + read_csv_data = sx.ReadCSVDataParameter() + read_csv_data.input_file_path = "/tmp/test_csv_data.csv" + read_csv_data.start_import_row = 2 + read_csv_data.delimiters = [','] + read_csv_data.custom_headers = [] + read_csv_data.column_data_types = [sx.DataType.float32,sx.DataType.float32,sx.DataType.float32,sx.DataType.float32,sx.DataType.float32,sx.DataType.float32,sx.DataType.int32] + read_csv_data.skipped_array_mask = [False,False,False,False,False,False,False] + read_csv_data.tuple_dims = [37989] + read_csv_data.headers_line = 1 + read_csv_data.header_mode = sx.ReadCSVDataParameter.HeaderMode.Line + params.insert(sx.ReadCSVFileParameter(ExampleFilter1.PARAM18_KEY, "CSV Importer Data", "Holds all relevant csv file data collected from the custom interface", read_csv_data)) + + params.insert(sx.Parameters.Separator("Read H5EBSD Parameter")) + read_h5ebsd_data = oa.ReadH5EbsdFileParameter.ValueType() + read_h5ebsd_data.euler_representation=0 + read_h5ebsd_data.end_slice=117 + read_h5ebsd_data.selected_array_names=["Confidence Index", "EulerAngles", "Fit", "Image Quality", "Phases", "SEM Signal", "X Position", "Y Position"] + read_h5ebsd_data.input_file_path="Data/Output/Reconstruction/Small_IN100.h5ebsd" + read_h5ebsd_data.start_slice=1 + read_h5ebsd_data.use_recommended_transform=True + params.insert(oa.ReadH5EbsdFileParameter(ExampleFilter1.PARAM19_KEY, "Import H5Ebsd File", "Object that holds all relevant information to import data from the file.", read_h5ebsd_data)) + + params.insert(sx.Parameters.Separator("Big Parameters")) + params.insert(sx.GeneratedFileListParameter(ExampleFilter1.PARAM4_KEY, 'Input File List', 'The values that are used to generate the input file list. See GeneratedFileListParameter for more information.', sx.GeneratedFileListParameter.ValueType())) + params.insert(sx.ArrayThresholdsParameter(ExampleFilter1.PARAM7_KEY, 'Data Thresholds', 'DataArray thresholds to mask', sx.ArrayThresholdSet())) + + params.insert(sx.Parameters.Separator("Multiple Linked Parameters")) + params.insert_linkable_parameter(sx.BoolParameter(ExampleFilter1.PARAM8_KEY, 'Bool Parameter', 'A boolean parameter', True)) + params.insert_linkable_parameter(sx.ChoicesParameter(ExampleFilter1.PARAM9_KEY, 'Choices Parameter', 'A choices parameter', 0, ["0", "1", "2"])) + params.insert(sx.Int32Parameter(ExampleFilter1.PARAM10_KEY, 'Int32 Parameter', 'An Integer Parameter', 42)) + params.link_parameters(ExampleFilter1.PARAM8_KEY, ExampleFilter1.PARAM10_KEY, True) + params.link_parameters(ExampleFilter1.PARAM9_KEY, ExampleFilter1.PARAM10_KEY, 1) + + return params + + def preflight_impl(self, data_structure: sx.DataStructure, args: dict, message_handler: sx.IFilter.MessageHandler, should_cancel: sx.AtomicBoolProxy) -> sx.IFilter.PreflightResult: + """This method preflights the filter and should ensure that all inputs are sanity checked as best as possible. Array + sizes can be checked if the arrays are actually know at preflight time. Some filters will not be able to report output + array sizes during preflight (segmentation filters for example). + :returns: + :rtype: sx.IFilter.PreflightResult + """ + + input_dir_path: str = [ExampleFilter1.INPUT_DIR_KEY] + input_file_path: str = [ExampleFilter1.INPUT_FILE_KEY] + output_dir_path: str = [ExampleFilter1.OUTPUT_DIR_KEY] + output_file_path: str = [ExampleFilter1.OUTPUT_FILE_KEY] + param1: float = [ExampleFilter1.PARAM1_KEY] + param2: bool = [ExampleFilter1.PARAM2_KEY] + param3: int = [ExampleFilter1.PARAM3_KEY] + param4: list[str] = [ExampleFilter1.PARAM4_KEY] + param5: str = [ExampleFilter1.PARAM5_KEY] + param6: sx.NumericType = [ExampleFilter1.PARAM6_KEY] + param7: set = [ExampleFilter1.PARAM7_KEY] + param8: bool = [ExampleFilter1.PARAM8_KEY] + param9: int = [ExampleFilter1.PARAM9_KEY] + param10: int = [ExampleFilter1.PARAM10_KEY] + vec2: list = [ExampleFilter1.VEC2_KEY] + vec3: list = [ExampleFilter1.VEC3_KEY] + vec4: list = [ExampleFilter1.VEC4_KEY] + vec4f: list = [ExampleFilter1.VEC4F_KEY] + vec6f: list = [ExampleFilter1.VEC6F_KEY] + + message_handler(sx.IFilter.Message(sx.IFilter.Message.Type.Info, f'Preflight: {input_dir_path}')) + return sx.IFilter.PreflightResult() + + def execute_impl(self, data_structure: sx.DataStructure, args: dict, message_handler: sx.IFilter.MessageHandler, should_cancel: sx.AtomicBoolProxy) -> sx.IFilter.ExecuteResult: + """ This method actually executes the filter algorithm and reports results. + :returns: + :rtype: sx.IFilter.ExecuteResult + """ + + input_dir_path: str = [ExampleFilter1.INPUT_DIR_KEY] + input_file_path: str = [ExampleFilter1.INPUT_FILE_KEY] + output_dir_path: str = [ExampleFilter1.OUTPUT_DIR_KEY] + output_file_path: str = [ExampleFilter1.OUTPUT_FILE_KEY] + param1: float = [ExampleFilter1.PARAM1_KEY] + param2: bool = [ExampleFilter1.PARAM2_KEY] + param3: int = [ExampleFilter1.PARAM3_KEY] + param4: list[str] = [ExampleFilter1.PARAM4_KEY] + param5: str = [ExampleFilter1.PARAM5_KEY] + param6: sx.NumericType = [ExampleFilter1.PARAM6_KEY] + param7: set = [ExampleFilter1.PARAM7_KEY] + param8: bool = [ExampleFilter1.PARAM8_KEY] + param9: int = [ExampleFilter1.PARAM9_KEY] + param10: int = [ExampleFilter1.PARAM10_KEY] + vec2: list = [ExampleFilter1.VEC2_KEY] + vec3: list = [ExampleFilter1.VEC3_KEY] + vec4: list = [ExampleFilter1.VEC4_KEY] + vec4f: list = [ExampleFilter1.VEC4F_KEY] + vec6f: list = [ExampleFilter1.VEC6F_KEY] + + message_handler(sx.IFilter.Message(sx.IFilter.Message.Type.Info, f'Execute: {input_dir_path}')) + return sx.Result() + diff --git a/wrapping/python/plugins/ExamplePlugin/ExampleFilter2.py b/wrapping/python/plugins/ExamplePlugin/ExampleFilter2.py new file mode 100644 index 0000000000..141e00699d --- /dev/null +++ b/wrapping/python/plugins/ExamplePlugin/ExampleFilter2.py @@ -0,0 +1,133 @@ +from typing import List +import simplnx as sx + +class ExampleFilter2: + """ + This section should contain the 'keys' that store each parameter. The value of the key should be snake_case. The name + of the value should be ALL_CAPITOL_KEY + """ + PARAM1_KEY = "param1" + PARAM2_KEY = "param2" + PARAM3_KEY = "param3" + PARAM4_KEY = "param4" + PARAM5_KEY = "param5" + PARAM6_KEY = "param6" + PARAM7_KEY = "param7" + PARAM8_KEY = "param8" + PARAM9_KEY = "param9" + PARAM10_KEY = "param10" + PARAM11_KEY = "param11" + PARAM12_KEY = "param12" + PARAM13_KEY = "param13" + PARAM14_KEY = "param14" + PARAM15_KEY = "param15" + PARAM16_KEY = "param16" + PARAM17_KEY = "param17" + PARAM18_KEY = "param18" + PARAM19_KEY = "param19" + PARAM20_KEY = "param20" + + def uuid(self) -> sx.Uuid: + """This returns the UUID of the filter. Each filter has a unique UUID value + :return: The Filter's Uuid value + :rtype: string + """ + return sx.Uuid('654236f1-1fc7-4a1f-9ade-5a6206ef4283') + + def human_name(self) -> str: + """This returns the name of the filter as a user of DREAM3DNX would see it + :return: The filter's human name + :rtype: string + """ + return 'Example Filter 2 (Python)' + + def class_name(self) -> str: + """The returns the name of the class that implements the filter + :return: The name of the implementation class + :rtype: string + """ + return 'ExampleFilter2' + + def name(self) -> str: + """The returns the name of filter + :return: The name of the filter + :rtype: string + """ + return 'ExampleFilter2' + + def default_tags(self) -> List[str]: + """This returns the default tags for this filter + :return: The default tags for the filter + :rtype: list + """ + return ['python'] + + def clone(self): + """Clones the filter + :return: A new instance of the filter + :rtype: ExampleFilter2 + """ + return ExampleFilter2() + + def parameters(self) -> sx.Parameters: + """This function defines the parameters that are needed by the filter. Parameters collect the values from the user + or through a pipeline file. + """ + params = sx.Parameters() + + params.insert(sx.Parameters.Separator("1st Group of Parameters")) + params.insert_linkable_parameter(sx.BoolParameter(ExampleFilter2.PARAM7_KEY, 'Bool Parameter', 'Example bool help text', True)) + params.insert_linkable_parameter(sx.ChoicesParameter(ExampleFilter2.PARAM3_KEY, 'Choices Parameter', 'Example choices help text', 0, ["foo", "bar", "baz"])) + + params.insert(sx.Parameters.Separator("2nd Group of Parameters")) + default_table = [[10, 20], [30, 40]] + row_info = sx.DynamicTableInfo.DynamicVectorInfo(0, "Row {}") + col_info = sx.DynamicTableInfo.DynamicVectorInfo(2, "Col {}") + dynamic_table_info = sx.DynamicTableInfo(sx.DynamicTableInfo.VectorInfo(row_info), sx.DynamicTableInfo.VectorInfo(col_info)) + params.insert(sx.DynamicTableParameter(ExampleFilter2.PARAM13_KEY, 'DynamicTableParameter', 'DynamicTableParameter Example Help Text', default_table, dynamic_table_info)) + + params.insert(sx.Parameters.Separator("3rd Group of Parameters")) + params.insert(sx.MultiPathSelectionParameter(ExampleFilter2.PARAM19_KEY, "Objects to copy", "A list of DataPaths to the DataObjects to be copied", [sx.DataPath(["Small IN100", "Scan Data", "Confidence Index"]), sx.DataPath(["Small IN100", "Scan Data", "Euler Angles"])])) + params.insert(sx.NeighborListSelectionParameter(ExampleFilter2.PARAM20_KEY, "Neighbor List", "List of the contiguous neighboring Features for a given Feature", sx.DataPath([]), set([sx.DataType.int32]))) + + params.insert(sx.Parameters.Separator("Calculator Parameter")) + calc_param = sx.CalculatorParameter.ValueType( sx.DataPath(["Small IN100","Scan Data"]), "Confidence Index * 10", sx.CalculatorParameter.AngleUnits.Radians) + params.insert(sx.CalculatorParameter(ExampleFilter2.PARAM18_KEY, "CalculatorParameter", "Example help text for calculator parameter", calc_param)) + + params.insert(sx.Parameters.Separator("Required Data Objects")) + params.insert(sx.DataGroupSelectionParameter(ExampleFilter2.PARAM9_KEY, 'DataGroupSelectionParameter', 'Example data group selection help text', sx.DataPath([]), set([sx.BaseGroup.GroupType.DataGroup]))) + params.insert(sx.DataPathSelectionParameter(ExampleFilter2.PARAM10_KEY, 'DataPathSelectionParameter', 'Example data path selection help text', sx.DataPath([]))) + params.insert(sx.ArraySelectionParameter(ExampleFilter2.PARAM6_KEY, 'Array Selection', 'Example array selection help text', sx.DataPath([]), sx.get_all_data_types(), [[1]])) + params.insert(sx.GeometrySelectionParameter(ExampleFilter2.PARAM11_KEY, 'GeometrySelectionParameter', 'Example geometry selection help text', sx.DataPath([]), set())) + params.insert(sx.MultiArraySelectionParameter(ExampleFilter2.PARAM12_KEY, 'MultiArraySelectionParameter', 'Example multiarray selection help text', [], set([sx.IArray.ArrayType.Any]), sx.get_all_data_types(), [[1]])) + params.insert(sx.AttributeMatrixSelectionParameter(ExampleFilter2.PARAM17_KEY, "Cell Attribute Matrix", "Example attribute matrix selection help text", sx.DataPath([]))) + + params.link_parameters(ExampleFilter2.PARAM7_KEY, ExampleFilter2.PARAM9_KEY, True) + params.link_parameters(ExampleFilter2.PARAM3_KEY, ExampleFilter2.PARAM10_KEY, 0) + params.link_parameters(ExampleFilter2.PARAM3_KEY, ExampleFilter2.PARAM6_KEY, 1) + params.link_parameters(ExampleFilter2.PARAM3_KEY, ExampleFilter2.PARAM11_KEY, 2) + + params.insert(sx.Parameters.Separator("Created Data Objects")) + params.insert(sx.DataGroupCreationParameter(ExampleFilter2.PARAM8_KEY, 'DataGroupCreationParameter', 'Example data group creation help text', sx.DataPath([]))) + params.insert(sx.ArrayCreationParameter(ExampleFilter2.PARAM5_KEY, 'Array Creation', 'Example array creation help text', sx.DataPath([]))) + + return params + + def preflight_impl(self, data_structure: sx.DataStructure, args: dict, message_handler: sx.IFilter.MessageHandler, should_cancel: sx.AtomicBoolProxy) -> sx.IFilter.PreflightResult: + """This method preflights the filter and should ensure that all inputs are sanity checked as best as possible. Array + sizes can be checked if the arrays are actually know at preflight time. Some filters will not be able to report output + array sizes during preflight (segmentation filters for example). + :returns: + :rtype: sx.IFilter.PreflightResult + """ + + return sx.IFilter.PreflightResult() + + def execute_impl(self, data_structure: sx.DataStructure, args: dict, message_handler: sx.IFilter.MessageHandler, should_cancel: sx.AtomicBoolProxy) -> sx.IFilter.ExecuteResult: + """ This method actually executes the filter algorithm and reports results. + :returns: + :rtype: sx.IFilter.ExecuteResult + """ + + return sx.Result() + diff --git a/wrapping/python/plugins/TestPlugin/InitializeData.py b/wrapping/python/plugins/ExamplePlugin/InitializeData.py similarity index 100% rename from wrapping/python/plugins/TestPlugin/InitializeData.py rename to wrapping/python/plugins/ExamplePlugin/InitializeData.py diff --git a/wrapping/python/plugins/ExamplePlugin/Plugin.py b/wrapping/python/plugins/ExamplePlugin/Plugin.py new file mode 100644 index 0000000000..e22f969ead --- /dev/null +++ b/wrapping/python/plugins/ExamplePlugin/Plugin.py @@ -0,0 +1,33 @@ + +""" +Insert documentation here. +""" + +from ExamplePlugin.ExampleFilter1 import ExampleFilter1 +from ExamplePlugin.ExampleFilter2 import ExampleFilter2 +from ExamplePlugin.CreateArray import CreateArrayFilter +from ExamplePlugin.InitializeData import InitializeDataPythonFilter +from ExamplePlugin.TemplateFilter import TemplateFilter + +# FILTER_INCLUDE_INSERT + +import simplnx as nx + +class ExamplePlugin: + def __init__(self) -> None: + pass + + def id(self) -> nx.Uuid: + return nx.Uuid('29b0bf6b-b67d-4030-92cd-bcdf7a7196d4') + + def name(self) -> str: + return 'ExamplePlugin' + + def description(self) -> str: + return 'ExamplePlugin' + + def vendor(self) -> str: + return 'Description' + + def get_filters(self): + return [ExampleFilter1,ExampleFilter2,CreateArrayFilter,InitializeDataPythonFilter,TemplateFilter] # FILTER_NAME_INSERT diff --git a/wrapping/python/plugins/TestPlugin/TemplateFilter.py b/wrapping/python/plugins/ExamplePlugin/TemplateFilter.py similarity index 100% rename from wrapping/python/plugins/TestPlugin/TemplateFilter.py rename to wrapping/python/plugins/ExamplePlugin/TemplateFilter.py diff --git a/wrapping/python/plugins/ExamplePlugin/__init__.py b/wrapping/python/plugins/ExamplePlugin/__init__.py new file mode 100644 index 0000000000..8117594a4e --- /dev/null +++ b/wrapping/python/plugins/ExamplePlugin/__init__.py @@ -0,0 +1,15 @@ +from ExamplePlugin.Plugin import ExamplePlugin + +from ExamplePlugin.ExampleFilter1 import ExampleFilter1 +from ExamplePlugin.ExampleFilter2 import ExampleFilter2 +from ExamplePlugin.CreateArray import CreateArrayFilter +from ExamplePlugin.InitializeData import InitializeDataPythonFilter +from ExamplePlugin.TemplateFilter import TemplateFilter + +# FILTER_INCLUDE_INSERT + +def get_plugin(): + return ExamplePlugin() + +__all__ = ['ExamplePlugin','ExampleFilter1', 'ExampleFilter2', 'CreateArrayFilter', 'InitializeDataPythonFilter', 'TemplateFilter', 'get_plugin'] # FILTER_NAME_INSERT + diff --git a/wrapping/python/plugins/TestPlugin/Plugin.py b/wrapping/python/plugins/TestPlugin/Plugin.py deleted file mode 100644 index 574a005246..0000000000 --- a/wrapping/python/plugins/TestPlugin/Plugin.py +++ /dev/null @@ -1,24 +0,0 @@ -from TestPlugin.CreateArray import CreateArrayFilter -from TestPlugin.InitializeData import InitializeDataPythonFilter -from TestPlugin.TemplateFilter import TemplateFilter -import simplnx as nx - -class TestPythonPlugin: - def __init__(self) -> None: - pass - - def id(self) -> nx.Uuid: - return nx.Uuid('a7d5db89-3bb3-4fed-a590-e2be9a71889d') - - def name(self) -> str: - return 'TestPythonPlugin' - - def description(self) -> str: - return 'Test' - - def vendor(self) -> str: - return 'John Smith' - - def get_filters(self): - return [CreateArrayFilter, InitializeDataPythonFilter, TemplateFilter] - diff --git a/wrapping/python/plugins/TestPlugin/__init__.py b/wrapping/python/plugins/TestPlugin/__init__.py deleted file mode 100644 index 571dd08add..0000000000 --- a/wrapping/python/plugins/TestPlugin/__init__.py +++ /dev/null @@ -1,10 +0,0 @@ -from TestPlugin.Plugin import TestPythonPlugin -from TestPlugin.CreateArray import CreateArrayFilter -from TestPlugin.InitializeData import InitializeDataPythonFilter -from TestPlugin.TemplateFilter import TemplateFilter - -def get_plugin(): - return TestPythonPlugin() - -__all__ = ['TestPythonPlugin', 'CreateArrayFilter', 'InitializeDataPythonFilter', 'TemplateFilter', 'get_plugin'] -