diff --git a/wrapping/python/docs/source/User_API.rst b/wrapping/python/docs/source/User_API.rst index 3dc77a1be5..3f9af04e43 100644 --- a/wrapping/python/docs/source/User_API.rst +++ b/wrapping/python/docs/source/User_API.rst @@ -29,6 +29,223 @@ Error & Warning Reporting else: print("No errors running the ConvertOrientations") +Creating Geometries +------------------ + +All the `simplnx` geometries can be created in Python using the following helper methods: + ++ create_image_geometry ++ create_rect_grid_geometry ++ create_vertex_geometry ++ create_edge_geometry ++ create_triangle_geometry ++ create_quad_geometry ++ create_tetrahedral_geometry ++ create_hexahedral_geometry + +The submodule `ArrayHandlingType` defines how existing arrays will be handled when creating a new geometry. It includes the following attributes: + +- **CopyArray**: The existing arrays will be copied into the new geometry. +- **MoveArray**: The existing arrays will be moved into the new geometry. + +Creating An Image Geometry +########################## + +To create an image geometry, use the `create_image_geometry` method. This method requires the following parameters: + +- `data_structure`: The data structure where the geometry will be created. +- `geometry_path`: The :ref:`DataPath ` where the geometry will be stored. +- `dimensions`: A list of dimensions for the image. +- `origin`: The origin coordinates of the image. +- `spacing`: The spacing between elements in the image. +- `cell_attr_matrix_name` (optional): The name of the cell attribute matrix. Defaults to "Cell Data". + +Example usage: + +.. code:: python + + import simplnx as nx + + # Create an image geometry + result: nx.Result = nx.create_image_geometry(data_structure=data_structure, geometry_path=nx.DataPath(["Image Geometry"]), dimensions=[100, 150, 200], origin=[0, 5, -2], spacing=[0.5, 0.5, 0.5], cell_attr_matrix_name='Image Data') + if result.valid(): + image_geom = data_structure[nx.DataPath(["Image Geometry"])] + print("Image Geometry Created!") + + +Creating A Rectilinear Grid Geometry +#################################### + +To create a rectilinear grid geometry, use the ``create_rect_grid_geometry`` method. This method requires the following parameters: + +- **data_structure**: The data structure where the geometry will be created. +- **geometry_path**: The :ref:`DataPath ` where the geometry will be stored. +- **x_bounds_path**: The :ref:`DataPath ` to the X bounds array. +- **y_bounds_path**: The :ref:`DataPath ` to the Y bounds array. +- **z_bounds_path**: The :ref:`DataPath ` to the Z bounds array. +- **cell_attr_matrix_name** (optional): The name of the cell attribute matrix. Defaults to "Cell Data". +- **array_handling** (optional): Specifies how to handle existing arrays. Defaults to ``ArrayHandlingType.CopyArray``. + +Example usage: + +.. code-block:: python + + import simplnx as nx + + # Create a rect grid geometry + result = nx.create_rect_grid_geometry(data_structure=data_structure, geometry_path=nx.DataPath(["Rect Grid Geometry"]), x_bounds_path=nx.DataPath(["Foo"]), y_bounds_path=nx.DataPath(["Y Bounds"]), z_bounds_path=nx.DataPath(["Z Bounds"]), cell_attr_matrix_name='Cell Data', array_handling=nx.ArrayHandlingType.CopyArray) + if result.valid(): + rect_grid_geom = data_structure[nx.DataPath(["Rect Grid Geometry"])] + print("Rect Grid Geometry Created!") + +Creating A Vertex Geometry +########################## + +To create a vertex geometry, use the ``create_vertex_geometry`` method. This method requires the following parameters: + +- **data_structure**: The data structure where the geometry will be created. +- **geometry_path**: The :ref:`DataPath ` where the geometry will be stored. +- **vertices_path**: The :ref:`DataPath ` to the vertices array. +- **vertex_attr_matrix_name** (optional): The name of the vertex attribute matrix. Defaults to "Vertex Data". +- **array_handling** (optional): Specifies how to handle existing arrays. Defaults to ``ArrayHandlingType.CopyArray``. + +Example usage: + +.. code-block:: python + + import simplnx as nx + + # Create a vertex geometry + result = nx.create_vertex_geometry(data_structure=data_structure, geometry_path=nx.DataPath(["Vertex Geometry"]), vertices_path=nx.DataPath("Vertices"), vertex_attr_matrix_name='Vertex Data', array_handling=nx.ArrayHandlingType.CopyArray) + if result.valid(): + vertex_geom = data_structure[nx.DataPath("Vertex Geometry")] + print("Vertex Geometry Created!") + +Creating An Edge Geometry +######################### + +To create an edge geometry, use the ``create_edge_geometry`` method. This method requires the following parameters: + +- **data_structure**: The data structure where the geometry will be created. +- **geometry_path**: The :ref:`DataPath ` where the geometry will be stored. +- **vertices_path**: The :ref:`DataPath ` to the vertices array. +- **edge_list_path**: The :ref:`DataPath ` to the edge list array. +- **vertex_attr_matrix_name** (optional): The name of the vertex attribute matrix. Defaults to "Vertex Data". +- **edge_attr_matrix_name** (optional): The name of the edge attribute matrix. Defaults to "Edge Data". +- **array_handling** (optional): Specifies how to handle existing arrays. Defaults to ``ArrayHandlingType.CopyArray``. + +Example usage: + +.. code-block:: python + + import simplnx as nx + + # Create an edge geometry + result = nx.create_edge_geometry(data_structure=data_structure, geometry_path=nx.DataPath(["Edge Geometry"]), vertices_path=nx.DataPath("Vertices"), edge_list_path=nx.DataPath("Edge List"), vertex_attr_matrix_name='Vertex Data', edge_attr_matrix_name='Edge Data', array_handling=nx.ArrayHandlingType.CopyArray) + if result.valid(): + edge_geom = data_structure[nx.DataPath("Edge Geometry")] + print("Edge Geometry Created!") + +Creating A Triangle Geometry +############################ + +To create a triangle geometry, use the ``create_triangle_geometry`` method. This method requires the following parameters: + +- **data_structure**: The data structure where the geometry will be created. +- **geometry_path**: The :ref:`DataPath ` where the geometry will be stored. +- **vertices_path**: The :ref:`DataPath ` to the vertices array. +- **triangle_list_path**: The :ref:`DataPath ` to the triangle list array. +- **vertex_attr_matrix_name** (optional): The name of the vertex attribute matrix. Defaults to "Vertex Data". +- **face_attr_matrix_name** (optional): The name of the face attribute matrix. Defaults to "Face Data". +- **array_handling** (optional): Specifies how to handle existing arrays. Defaults to ``ArrayHandlingType.CopyArray``. + +Example usage: + +.. code-block:: python + + import simplnx as nx + + # Create a triangle geometry + result = nx.create_triangle_geometry(data_structure=data_structure, geometry_path=nx.DataPath(["Triangle Geometry"]), vertices_path=nx.DataPath("Vertices"), triangle_list_path=nx.DataPath("Triangle List"), vertex_attr_matrix_name='Vertex Data', face_attr_matrix_name='Face Data', array_handling=nx.ArrayHandlingType.CopyArray) + if result.valid(): + triangle_geom = data_structure[nx.DataPath("Triangle Geometry")] + print("Triangle Geometry Created!") + +Creating A Quadrilateral Geometry +################################# + +To create a quadrilateral geometry, use the ``create_quad_geometry`` method. This method requires the following parameters: + +- **data_structure**: The data structure where the geometry will be created. +- **geometry_path**: The :ref:`DataPath ` where the geometry will be stored. +- **vertices_path**: The :ref:`DataPath ` to the vertices array. +- **quad_list_path**: The :ref:`DataPath ` to the quadrilateral list array. +- **vertex_attr_matrix_name** (optional): The name of the vertex attribute matrix. Defaults to "Vertex Data". +- **face_attr_matrix_name** (optional): The name of the face attribute matrix. Defaults to "Quad Data". +- **array_handling** (optional): Specifies how to handle existing arrays. Defaults to ``ArrayHandlingType.CopyArray``. + +Example usage: + +.. code-block:: python + + import simplnx as nx + + # Create a quad geometry + result = nx.create_quad_geometry(data_structure=data_structure, geometry_path=nx.DataPath(["Quad Geometry"]), vertices_path=nx.DataPath("Vertices"), quad_list_path=nx.DataPath("Quad List"), vertex_attr_matrix_name='Vertex Data', face_attr_matrix_name='Quad Data', array_handling=nx.ArrayHandlingType.CopyArray) + if result.valid(): + quad_geom = data_structure[nx.DataPath("Quad Geometry")] + print("Quad Geometry Created!") + +Creating A Tetrahedral Geometry +############################### + +To create a tetrahedral geometry, use the ``create_tetrahedral_geometry`` method. This method requires the following parameters: + +- **data_structure**: The data structure where the geometry will be created. +- **geometry_path**: The :ref:`DataPath ` where the geometry will be stored. +- **vertices_path**: The :ref:`DataPath ` to the vertices array. +- **tetrahedral_list_path**: The :ref:`DataPath ` to the tetrahedral list array. +- **vertex_attr_matrix_name** (optional): The name of the vertex attribute matrix. Defaults to "Vertex Data". +- **cell_attr_matrix_name** (optional): The name of the cell attribute matrix. Defaults to "Cell Data". +- **array_handling** (optional): Specifies how to handle existing arrays. Defaults to ``ArrayHandlingType.CopyArray``. + +Example usage: + +.. code-block:: python + + import simplnx as nx + + # Create a tetrahedral geometry + result = nx.create_tetrahedral_geometry(data_structure=data_structure, geometry_path=nx.DataPath(["Tetrahedral Geometry"]), vertices_path=nx.DataPath("Vertices"), tetrahedral_list_path=nx.DataPath("Tetrahedral List"), vertex_attr_matrix_name='Vertex Data', cell_attr_matrix_name='Cell Data', array_handling=nx.ArrayHandlingType.CopyArray) + if result.valid(): + tetrahedral_geom = data_structure[nx.DataPath("Tetrahedral Geometry")] + print("Tetrahedral Geometry Created!") + +Creating A Hexahedral Geometry +############################## + +To create a hexahedral geometry, use the ``create_hexahedral_geometry`` method. This method requires the following parameters: + +- **data_structure**: The data structure where the geometry will be created. +- **geometry_path**: The :ref:`DataPath ` where the geometry will be stored. +- **vertices_path**: The :ref:`DataPath ` to the vertices array. +- **hexahedral_list_path**: The :ref:`DataPath ` to the hexahedral list array. +- **vertex_attr_matrix_name** (optional): The name of the vertex attribute matrix. Defaults to "Vertex Data". +- **cell_attr_matrix_name** (optional): The name of the cell attribute matrix. Defaults to "Cell Data". +- **array_handling** (optional): Specifies how to handle existing arrays. Defaults to ``ArrayHandlingType.CopyArray``. + +Example usage: + +.. code-block:: python + + import simplnx as nx + + # Create a hexahedral geometry + result = nx.create_hexahedral_geometry(data_structure=data_structure, geometry_path=nx.DataPath(["Hexahedral Geometry"]), vertices_path=nx.DataPath("Vertices"), hexahedral_list_path=nx.DataPath("Hexahedral List"), vertex_attr_matrix_name='Vertex Data', cell_attr_matrix_name='Cell Data', array_handling=nx.ArrayHandlingType.CopyArray) + if result.valid(): + hexahedral_geom = data_structure[nx.DataPath("Hexahedral Geometry")] + print("Hexahedral Geometry Created!") + General Parameters ------------------