SIMPLNX Python API

Error & Warning Reporting

class IFilter.ExecuteResult

The object that encapsulates any warnings or errors from either preflighting or executing a simplnx.Filter object. It can be queried for the list of errors or warnings and thus printed if needed.

result = cxor.ConvertOrientations.execute(data_structure=data_structure,
                                    input_orientation_array_path=array_path,
                                    input_type=0,
                                    output_orientation_array_name='Quaternions',
                                    output_type=2)
if len(result.warnings) != 0:
   for w in result.warnings:
      print(f'Warning: ({w.code}) {w.message}')

has_errors = len(result.errors) != 0
if has_errors:
   for err in result.errors:
      print(f'Error: ({err.code}) {err.message}')
      raise RuntimeError(result)
else:
   print(f"{filter.name()} :: No errors running the filter")

General Parameters

class nx.ArrayCreationParameter

This parameter holds a DataPath value that points to the location within the DataStructure of where the DataArray will be created.

data_path = nx.DataPath("Small IN100/Scan Data/Data")
class nx.ArraySelectionParameter

This parameter holds a DataPath value that points to the location within the DataStructure of where the DataArray will be read.

data_path = nx.DataPath("Small IN100/Scan Data/Data")
class nx.ArrayThresholdsParameter

This parameter holds a ArrayThresholdSet object and is used specifically for the simplnx.MultiThresholdObjectsFilter() filter. This parameter should not be directly invoked but instead it’s ArrayThresholdSet is invoked and used.

class nx.ArrayThresholdSet

This class holds a list of ArrayThreshold objects.

Variables:

thresholds – List[ArrayThreshold] objects

class ArrayThresholdSet.ArrayThreshold

This class holds the values that are used for comparison in the simplnx.MultiThresholdObjectsFilter() filter.

Variables:

  • array_path – The DataPath to the array to use for this ArrayThreshold

  • comparison – Int. The comparison operator to use. 0=”>”, 1=”<”, 2=”=”, 3=”!=”

  • 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.

threshold_1 = nx.ArrayThreshold()
threshold_1.array_path = nx.DataPath("Small IN100/Scan Data/Confidence Index")
threshold_1.comparison = nx.ArrayThreshold.ComparisonType.GreaterThan
threshold_1.value = 0.1

threshold_2 = nx.ArrayThreshold()
threshold_2.array_path = nx.DataPath("Small IN100/Scan Data/Image Quality")
threshold_2.comparison = nx.ArrayThreshold.ComparisonType.GreaterThan
threshold_2.value = 120

threshold_set = nx.ArrayThresholdSet()
threshold_set.thresholds = [threshold_1, threshold_2]
threshold_set.union_op = nx.IArrayThreshold.UnionOperator.And
result = nx.MultiThresholdObjectsFilter.execute(data_structure=data_structure,
                                    array_thresholds=threshold_set,
                                    created_data_path="Mask",
                                    created_mask_type=nx.DataType.boolean)
class nx.AttributeMatrixSelectionParameter

This parameter holds a DataPath value that points to the location within the DataStructure of a selected AttributeMatrix.

data_path = nx.DataPath("Small IN100/Scan Data")
class nx.BoolParameter

This parameter holds a True/False value and is represented in the UI with a check box

enable_some_feature = True
class nx.CalculatorParameter

This parameter has a single member type “ValueType” that can be constructed with the necessary values.

class ValueType
Variables:

  • selected_group – The DataGroup or AttributeMatrix that contains the DataArray that will be used in the equations

  • equation – String. The equation that will be evaluated

  • units – nx.CalculatorParameter.AngleUnits.Radians or nx.CalculatorParameter.AngleUnits.Degrees

selected_group = nx.DataPath("Small IN100/Scan Data")
infix_equation = "Confidence Index * 10"
calc_param = nx.CalculatorParameter.ValueType( selected_group, infix_equation, nx.CalculatorParameter.AngleUnits.Radians)
result = nx.ArrayCalculatorFilter.execute(data_structure = data_structure,
                                          calculated_array=nx.DataPath("Small IN100/Scan Data/Calulated CI"),
                                          calculator_parameter = calc_param,
                                          scalar_type=nx.NumericType.float32)
class nx.ChoicesParameter

This parameter holds a single value from a list of choices in the form of an integer. The filter documentation should have the valid values to chose from. It is represented in the UI through a ComboBox drop down menu. It can be initialized with an integer type.

a_combo_box_value = 2
class nx.DataGroupCreationParameter

This parameter holds a DataPath value that points to the location within the DataStructure of a DataGroup that will be created by the filter.

data_path = nx.DataPath("Small IN100/Scan Data")
class nx.DataGroupSelectionParameter

This parameter holds a DataPath value that points to the location within the DataStructure of a DataGroup that will be used in the filter.

data_path = nx.DataPath("Small IN100/Scan Data")
class nx.DataObjectNameParameter

This parameter holds a string value. It typically is the name of a DataObject within the DataStructure.

data_path = "Small IN100"
class nx.DataPathSelectionParameter

This parameter holds a DataPath object that represents an object within the DataStructure.

data_path = nx.DataPath("Small IN100/Scan Data/Confidence Index")
class nx.DataStoreFormatParameter

This parameter holds a string value that represents the kind of DataStore that will be used to store the data. Depending on the version of simplnx being used, there can be both in-core and out-of-core DataStore objects available.

class nx.DataTypeParameter

This parameter holds an enumeration value that represents the numerical type for created arrays. The possible values are.

nx.DataType.int8
nx.DataType.uint8
nx.DataType.int16
nx.DataType.uint16
nx.DataType.int32
nx.DataType.uint32
nx.DataType.int64
nx.DataType.uint64
nx.DataType.float32
nx.DataType.float64
nx.DataType.boolean
class nx.Dream3dImportParameter

This class holds the information necessary to import a .dream3d file through the ImportData object.

Variables:

ValueType – ImportData

class ValueType

The ImportData object has 2 member variables that can be set.

Variables:

  • file_path – Path to the .dream3d file on the file system

  • data_paths – List of DataPath objects. Use the python ‘None’ value to indicate that you want to read ALL the data from file.

import_data = nx.Dream3dImportParameter.ImportData()
import_data.file_path = "/private/tmp/basic_ebsd.dream3d"
import_data.data_paths = None
result = nx.ReadDREAM3DFilter.execute(data_structure=data_structure, import_file_data=import_data)
class nx.DynamicTableParameter

This paramter holds values from a 2D table of values. This parameter can be initialized from a python “list of lists”. For a 2D table the values are rastered with the columns moving the fastest. For example in the code below we are creating a 2D DynamicTable info where the first row is “1,2,3” and the second row is “4,5,6”

dynamic_table_value = [[1,2,3][4,5,6]]
class nx.EnsembleInfoParameter

This parameter is represented as 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 OrientationAnalysis.CreateEnsembleInfoFilter() filter.

ensemble_info_parameter = []
ensemble_info_parameter.append(["Hexagonal-High 6/mmm","Primary","Phase 1"])
ensemble_info_parameter.append(["Cubic-High m-3m","Primary","Phase 2"])
result = cxor.CreateEnsembleInfoFilter.execute(data_structure=data_structure,
                         cell_ensemble_attribute_matrix_name=nx.DataPath(["Phase Data"]),
                         crystal_structures_array_name="CrystalStructures",
                         phase_names_array_name="Phase Names",
                         phase_types_array_name="Primary",
                         ensemble=ensemble_info_parameter
                         )
class nx.FileSystemPathParameter

This parameter represents a file or folder on the local filesystem (or a network mounted filesystem) and can be instantiated using a “PathLike” python class or python string.

a_file_system_path = "/The/Path/To/The/File/Or/Directory"
class nx.GenerateColorTableParameter(Updated v1.2.6)

This parameter is used specifically for the simplnx.GenerateColorTableFilter() filter. This parameter represents a string value that corresponds to an RGB Preset Name and can be instantiated using a simple python string type.

Default RGB Preset Names are as follows:

  • “Rainbow Desaturated”

  • “Cold and Hot”

  • “Black-Body Radiation”

  • “X Ray”

  • “Grayscale”

  • “Black, Blue and White”

  • “Black, Orange and White”

  • “Rainbow Blended White”

  • “Rainbow Blended Grey”

  • “Rainbow Blended Black”

  • “Blue to Yellow”

  • “jet”

  • “rainbow”

  • “Haze”

  • “hsv”

result = nx.GenerateColorTableFilter.execute(data_structure=data_structure,
                                        rgb_array_path="CI Color",
                                        input_data_array_path=nx.DataPath("Small IN100/Scan Data/Confidence Index"),
                                        selected_preset="hsv")
class nx.GeneratedFileListParameter

This parameter describes the necessary pieces of information to construct a list of files that is then handed off to the filter. In order to instantiate this parameter the programmer should use the GeneratedFileListParameter.ValueType data member of the GeneratedFileListParameter.

Variables:

ValueType – data member that holds values to generate a file list

class ValueType
Variables:

  • input_path – The file system path to the directory that contains the input files

  • ordering – This describes how to generate the files. One of nx.GeneratedFileListParameter.Ordering.LowToHigh or nx.GeneratedFileListParameter.Ordering.HighToLow

  • file_prefix – The string part of the file name that appears before the index digits

  • file_suffix – The string part of the file anem that appears after the index digits

  • file_extension – The file extension of the input files includeing the “.” character.

  • start_index – The starting index value

  • end_index – The ending index value (inclusive)

  • increment_index – The value of how much to increment the index value when generating the file list

  • padding_digits – The maximum number of digits to pad values out to.

For example 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

generated_file_list_value = nx.GeneratedFileListParameter.ValueType()
generated_file_list_value.input_path = "DREAM3DNXData/Data/Porosity_Image"
generated_file_list_value.ordering = nx.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

result = cxitk.ITKImportImageStack.execute(data_structure=data_structure,
                                  cell_data_name="Cell Data",
                                  image_data_array_path="Image Data",
                                  output_image_geometry_path=nx.DataPath(["Image Stack"]),
                                  image_transform_choice=0,
                                  input_file_list_info=generated_file_list_value,
                                  origin=[0., 0., 0.],
                                  spacing=[1., 1.,1.])
if len(result.errors) != 0:
    print('Errors: {}', result.errors)
    print('Warnings: {}', result.warnings)
else:
    print("No errors running the filter")
class nx.GeometrySelectionParameter

This parameter represents the DataPath to a valid simplnx.Geometry()

class nx.ReadCSVDataParameter

This parameter is used for the simplnx.ReadCSVFileFilter() and holds the information to import a file formatted as table data where each column of data is a single array.

  • 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 but will continue to the end of the file.

The primary python object that will hold the information to pass to the filter is the ReadCSVDataParameter class described below.

Variables:

ValueType – ReadCSVDataParameter

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 the filter will execute correctly.

Variables:

  • input_file_path – “PathLike”. The path to the input file on the file system.

  • start_import_row – Int. What line number does the data start on. ONE (1) Based numbering scheme.

  • delimiters – List[string]. List of delimiters that will be used to separate the lines of the file into columns.

  • consecutive_delimiters – Bool. Should consecutive delimiters be counted as a single delimiter.

  • 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 DataArray.

  • data_types – List[nx.DataType]. The DataType, one per column, that indicates the kind of native numerical values (int, float… ) that will be used in the created DataArray.

  • skipped_array_mask – List[bool]. Booleans, one per column, that indicate whether or not to skip importing each created DataArray.

  • tuple_dims – List[int]. The tuple dimensions for the created DataArrays.

  • headers_line – Int. The line number of the file that has the headers listed on a single line. ONE (1) based indexing.

  • header_mode – ‘nx.ReadCSVDataParameter.HeaderMode.’. Can be one of ‘nx.ReadCSVDataParameter.HeaderMode.Line’ or ‘nx.ReadCSVDataParameter.HeaderMode.Custom’.

data_structure = nx.DataStructure()

# Example File has 7 columns to import
read_csv_data = nx.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 = [nx.DataType.float32,nx.DataType.float32,nx.DataType.float32,nx.DataType.float32,nx.DataType.float32,nx.DataType.float32,nx.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 = nx.ReadCSVDataParameter.HeaderMode.Line

# This will store the imported arrays into a newly generated DataGroup
result = nx.ReadCSVFileFilter.execute(data_structure=data_structure,
                                      # This will store the imported arrays into a newly generated DataGroup
                                      created_data_group=nx.DataPath(["Imported Data"]),
                                      # We are not using this parameter but it still needs a value
                                      selected_data_group=nx.DataPath(),
                                      # Use an existing DataGroup or AttributeMatrix. If an AttributemMatrix is used, the total number of tuples must match
                                      use_existing_group=False,
                                      # The ReadCSVData object with all member variables set.
                                      read_csv_data=read_csv_data # The ReadCSVData object with all member variables set.
                                      )
class nx.ReadH5EbsdFileParameter

This parameter is used for the orientationAnalysis.ReadH5EbsdFilter() and holds the information to import the EBSD data from the file.

The primary python object that will hold the information to pass to the filter is the ReadH5EbsdFileParameter class described below.

Variables:

ValueType – ReadH5EbsdFileParameter

class ReadH5EbsdFileParameter

The ReadH5EbsdFileParameter class holds all the necessary information to import EBSD data stored in the H5Ebsd file.

Variables:

  • euler_representation – Int. 0=Radians, 1=Degrees

  • start_slice – Int. The starting slice of EBSD data to import

  • end_slice – Int. The ending slice (inclusive) of EBSD data to import

  • selected_array_names – List[string]. The names of the EBSD data to import. These may differ slightly between the various OEMs.

  • input_file_path – PathLike. The path to the .h5ebsd file to read.

  • use_recommended_transform – Bool. Apply the stored sample and crystal reference frame transformations.

data_structure = nx.DataStructure()
# Create the ReadH5EbsdFileParameter and assign values to it.
h5ebsdParameter = cxor.ReadH5EbsdFileParameter.ValueType()
h5ebsdParameter.euler_representation=0
h5ebsdParameter.end_slice=117
h5ebsdParameter.selected_array_names=["Confidence Index", "EulerAngles", "Fit", "Image Quality", "Phases", "SEM Signal", "X Position", "Y Position"]
h5ebsdParameter.input_file_path="Data/Output/Reconstruction/Small_IN100.h5ebsd"
h5ebsdParameter.start_slice=1
h5ebsdParameter.use_recommended_transform=True

# Execute Filter with Parameters
result = cxor.ReadH5EbsdFilter.execute(
   data_structure=data_structure,
   cell_attribute_matrix_name="CellData",
   cell_ensemble_attribute_matrix_name="CellEnsembleData",
   data_container_name=nx.DataPath("DataContainer"),
   read_h5_ebsd_parameter=h5ebsdParameter
)
class nx.ReadHDF5DatasetParameter

This parameter is used for the simplnx.ReadHDF5DatasetFilter and holds the information to import specific data sets from within the HDF5 file into DREAM3D/simplnx

class ValueType

This holds the main parameter values which consist of the following data members

Variables:

  • input_file – A “PathLike” value to the HDF5 file on the file system

  • datasets – list[ReadHDF5DatasetParameter.DatasetImportInfo, ….]

  • parent – Optional: The DataPath object to a parente group to create the DataArray into. If left blank the DataArray will be created at the top level of the DataStructure

class DatasetImportInfo

The DatasetImportInfo class has 3 data members that hold information on a specific data set inside the HDF5 file that the programmer wants to import.

Variables:

  • dataset_path – string. The internal HDF5 path to the data set expressed as a path like string “/foo/bar/dataset”

  • tuple_dims – string. A comma separated list of the tuple dimensions from SLOWEST to FASTEST dimensions (“117,201,189”)

  • component_dims – string. A comma separated list of the component dimensions from SLOWEST to FASTEST dimensions (“1”)

dataset1 = nx.ReadHDF5DatasetParameter.DatasetImportInfo()
dataset1.dataset_path = "/DataStructure/DataContainer/CellData/Confidence Index"
dataset1.tuple_dims = "117,201,189"
dataset1.component_dims = "1"

dataset2 = nx.ReadHDF5DatasetParameter.DatasetImportInfo()
dataset2.dataset_path = "/DataStructure/DataContainer/CellData/EulerAngles"
dataset2.tuple_dims = "117,201,189"
dataset2.component_dims = "3"

import_hdf5_param = nx.ReadHDF5DatasetParameter.ValueType()
import_hdf5_param.input_file = "SmallIN100_Final.dream3d"
import_hdf5_param.datasets = [dataset1, dataset2]
# import_hdf5_param.parent = nx.DataPath(["Imported Data"])
result = nx.ReadHDF5DatasetFilter.execute(data_structure=data_structure,
                                    import_hd_f5_file=import_hdf5_param
                                    )
class nx.MultiArraySelectionParameter

This parameter represents a list of DataPath objects where each DataPath object points to a DataArray

path_list = [nx.DataPath(["Group 1", "Array"]), nx.DataPath(["Group 1", "Array 2"])]
class nx.MultiPathSelectionParameter

This parameter represents a list of DataPath objects. The end point of each DataPath object can be any object in the DataStructure

path_list = [nx.DataPath(["Group 1", "Array"]), nx.DataPath(["Group 1", "Array 2"])]
class nx.NeighborListSelectionParameter

This parameter represents a DataPath object that has an end point of a ‘nx.NeighborList’ object

class nx.NumericTypeParameter

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.

  • nx.NumericType.int8 = 0

  • nx.NumericType.uint8= 1

  • nx.NumericType.int16= 2

  • nx.NumericType.uint16= 3

  • nx.NumericType.int32= 4

  • nx.NumericType.uint32= 5

  • nx.NumericType.int64= 6

  • nx.NumericType.uint64= 7

  • nx.NumericType.float32= 8

  • nx.NumericType.float64= 9

array_type = nx.NumericType.float32
class nx.StringParameter

This parameter represents a string value and can be instantiated using a simple python string type.

Numerical Parameters

This group of parameters wrap a specific native C++ numeric type. They can be instantiated using standard python integers or decimal values. For example.

some_varible = 10
other_variable = 22.342
class nx.Int8Parameter

Represents a signed 8 bit integer value

class nx.UInt8Parameter

Represents a unsigned 8 bit integer value

class nx.Int16Parameter

Represents a signed 16 bit integer value

class nx.UInt16Parameter

Represents a unsigned 16 bit integer value

class nx.Int32Parameter

Represents a signed 32 bit integer value

class nx.UInt32Parameter

Represents a unsigned 32 bit integer value

class nx.Int64Parameter

Represents a signed 64 bit integer value

class nx.UInt64Parameter

Represents a unsigned 64 bit integer value

class nx.Float32Parameter

Represents a 32 bit floating point value

class nx.Float64Parameter

Represents a 64 bit floating point value

Numerical Vector Parameters

This group represents a parameter that is being 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. For example if a parameter is a 4x1 Float32 value then it would be initialized by:

origin = [10.0, 20.0, 33.3, 0.2342]
class nx.VectorInt8Parameter

Represents a vector of signed 8 bit integer values

class nx.VectorUInt8Parameter

Represents a vector of unsigned 8 bit integer values

class nx.VectorInt16Parameter

Represents a vector of signed 16 bit integer values

class nx.VectorUInt16Parameter

Represents a vector of unsigned 16 bit integer values

class nx.VectorInt32Parameter

Represents a vector of signed 32 bit integer values

class nx.VectorUInt32Parameter

Represents a vector of unsigned 32 bit integer values

class nx.VectorInt64Parameter

Represents a vector of signed 64 bit integer values

class nx.VectorUInt64Parameter

Represents a vector of unsigned 64 bit integer values

class nx.VectorFloat32Parameter

Represents a vector of 32 bit floating point values

class nx.VectorFloat64Parameter

Represents a vector of 64 bit floating point values