feat: add FillPartialArrays vtk filter and paraview plugin (#105)

New feature to identify and fill partial arrays in a VTK mesh with specified or default values.

A core FillPartialArrays filter provides the backend logic, and a ParaView plugin is included for user interaction.

Key Enhancements:
Customization: Users can now programmatically choose which attributes to fill and specify a custom value. The feature supports setting different fill values for each component in multi-component arrays.

Type Preservation: The filter was improved to preserve the original vtkDataType of the array being modified.

Robustness: Added better error handling, including checks for missing attributes and a new function to test if an array is partial.

Refactoring & Fixes:
The codebase has been significantly cleaned, with clearer variable names, improved documentation, and better log messages for user output.

Fixed bugs related to the default fill value for uint types and issues in attribute transfer functions.

Updated and added new tests for the filter and its utility functions.

Applied multiple formatting changes to align with CI standards.

Co-authored-by: paloma-martinez <104762252+paloma-martinez@users.noreply.github.com>

Author: RomainBaville

docs/geos_mesh_docs/processing.rst

@@ -4,6 +4,15 @@ Processing filters
 The `processing` module of `geos-mesh` package contains filters to process meshes.
 
 
+geos.mesh.processing.FillPartialArrays filter
+----------------------------------------------
+
+.. automodule:: geos.mesh.processing.FillPartialArrays
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
 geos.mesh.processing.meshQualityMetricHelpers module
 -----------------------------------------------------
 
@@ -12,6 +21,7 @@ geos.mesh.processing.meshQualityMetricHelpers module
     :undoc-members:
     :show-inheritance:
 
+
 geos.mesh.processing.SplitMesh filter
 --------------------------------------
 

docs/geos_pv_docs/processing.rst

@@ -1,6 +1,11 @@
 Post-/Pre-processing
 =========================
 
+PVFillPartialArrays
+--------------------
+.. automodule:: geos.pv.plugins.PVFillPartialArrays
+
+
 PVSplitMesh
 ----------------------------------
 

geos-mesh/src/geos/mesh/processing/FillPartialArrays.py

@@ -0,0 +1,154 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright 2023-2024 TotalEnergies.
+# SPDX-FileContributor: Romain Baville, Martin Lemay
+
+from typing_extensions import Self
+from typing import Union, Any
+
+from geos.utils.Logger import logging, Logger, getLogger
+from geos.mesh.utils.arrayModifiers import fillPartialAttributes
+from geos.mesh.utils.arrayHelpers import isAttributeInObject
+
+from vtkmodules.vtkCommonDataModel import vtkMultiBlockDataSet
+
+__doc__ = """
+Fill partial attributes of the input mesh with constant values per component.
+
+Input mesh is vtkMultiBlockDataSet and attributes to fill must be partial.
+
+The list of filling values per attribute is given by a dictionary.
+Its keys are the attribute names and its items are the list of filling values for each component.
+
+If the list of filling value is None, attributes are filled with the same constant value for each component;
+0 for uint data, -1 for int data and nan for float data.
+
+To use a handler of yours for the logger, set the variable 'speHandler' to True and add it to the filter
+with the member function addLoggerHandler.
+
+To use it:
+
+.. code-block:: python
+
+    from geos.mesh.processing.FillPartialArrays import FillPartialArrays
+
+    # Filter inputs.
+    multiBlockDataSet: vtkMultiBlockDataSet
+    dictAttributesValues: dict[ str, Union[ list[ Any ], None ] ]
+    # Optional inputs.
+    speHandler: bool
+
+    # Instantiate the filter.
+    filter: FillPartialArrays = FillPartialArrays( multiBlockDataSet, dictAttributesValues, speHandler )
+
+    # Set the handler of yours (only if speHandler is True).
+    yourHandler: logging.Handler
+    filter.addLoggerHandler( yourHandler )
+
+    # Do calculations.
+    filter.applyFilter()
+"""
+
+loggerTitle: str = "Fill Partial Attribute"
+
+
+class FillPartialArrays:
+
+    def __init__(
+        self: Self,
+        multiBlockDataSet: vtkMultiBlockDataSet,
+        dictAttributesValues: dict[ str, Union[ list[ Any ], None ] ],
+        speHandler: bool = False,
+    ) -> None:
+        """Fill partial attributes with constant value per component.
+
+        If the list of filling values for an attribute is None, it will filled with the default value for each component:
+            0 for uint data.
+            -1 for int data.
+            nan for float data.
+
+        Args:
+            multiBlockDataSet (vtkMultiBlockDataSet): The mesh where to fill the attribute.
+            dictAttributesValues (dict[str, Any]): The dictionary with the attribute to fill as keys and the list of filling values as items.
+            speHandler (bool, optional): True to use a specific handler, False to use the internal handler.
+                Defaults to False.
+        """
+        self.multiBlockDataSet: vtkMultiBlockDataSet = multiBlockDataSet
+        self.dictAttributesValues: dict[ str, Union[ list[ Any ], None ] ] = dictAttributesValues
+
+        # Logger.
+        self.logger: Logger
+        if not speHandler:
+            self.logger = getLogger( loggerTitle, True )
+        else:
+            self.logger = logging.getLogger( loggerTitle )
+            self.logger.setLevel( logging.INFO )
+
+    def setLoggerHandler( self: Self, handler: logging.Handler ) -> None:
+        """Set a specific handler for the filter logger.
+
+        In this filter 4 log levels are use, .info, .error, .warning and .critical, be sure to have at least the same 4 levels.
+
+        Args:
+            handler (logging.Handler): The handler to add.
+        """
+        if not self.logger.hasHandlers():
+            self.logger.addHandler( handler )
+        else:
+            self.logger.warning(
+                "The logger already has an handler, to use yours set the argument 'speHandler' to True during the filter initialization."
+            )
+
+    def applyFilter( self: Self ) -> bool:
+        """Create a constant attribute per region in the mesh.
+
+        Returns:
+            boolean (bool): True if calculation successfully ended, False otherwise.
+        """
+        self.logger.info( f"Apply filter { self.logger.name }." )
+
+        for attributeName in self.dictAttributesValues:
+            self._setPieceRegionAttribute( attributeName )
+            if self.onPoints is None:
+                self.logger.error( f"{ attributeName } is not in the mesh." )
+                self.logger.error( f"The attribute { attributeName } has not been filled." )
+                self.logger.error( f"The filter { self.logger.name } failed." )
+                return False
+
+            if self.onBoth:
+                self.logger.error(
+                    f"Their is two attribute named { attributeName }, one on points and the other on cells. The attribute must be unique."
+                )
+                self.logger.error( f"The attribute { attributeName } has not been filled." )
+                self.logger.error( f"The filter { self.logger.name } failed." )
+                return False
+
+            if not fillPartialAttributes( self.multiBlockDataSet,
+                                          attributeName,
+                                          onPoints=self.onPoints,
+                                          listValues=self.dictAttributesValues[ attributeName ],
+                                          logger=self.logger ):
+                self.logger.error( f"The filter { self.logger.name } failed." )
+                return False
+
+        self.logger.info( f"The filter { self.logger.name } succeed." )
+
+        return True
+
+    def _setPieceRegionAttribute( self: Self, attributeName: str ) -> None:
+        """Set the attribute self.onPoints and self.onBoth.
+
+        self.onPoints is True if the region attribute is on points, False if it is on cells, None otherwise.
+
+        self.onBoth is True if a region attribute is on points and on cells, False otherwise.
+
+        Args:
+           attributeName (str): The name of the attribute to verify.
+        """
+        self.onPoints: Union[ bool, None ] = None
+        self.onBoth: bool = False
+        if isAttributeInObject( self.multiBlockDataSet, attributeName, False ):
+            self.onPoints = False
+        if isAttributeInObject( self.multiBlockDataSet, attributeName, True ):
+            if self.onPoints is False:
+                self.onBoth = True
+            self.onPoints = True

geos-mesh/src/geos/mesh/utils/arrayModifiers.py

@@ -41,6 +41,7 @@
     isAttributeGlobal,
     getVtkArrayTypeInObject,
     getVtkArrayTypeInMultiBlock,
+    getNumberOfComponentsMultiBlock,
 )
 from geos.mesh.utils.multiblockHelpers import (
     getBlockElementIndexesFlatten,
@@ -61,18 +62,18 @@ def fillPartialAttributes(
     multiBlockDataSet: Union[ vtkMultiBlockDataSet, vtkCompositeDataSet, vtkDataObject ],
     attributeName: str,
     onPoints: bool = False,
-    value: Any = np.nan,
+    listValues: Union[ list[ Any ], None ] = None,
     logger: Union[ Logger, None ] = None,
 ) -> bool:
-    """Fill input partial attribute of multiBlockDataSet with the same value for all the components.
+    """Fill input partial attribute of multiBlockDataSet with a constant value per component.
 
     Args:
         multiBlockDataSet (vtkMultiBlockDataSet | vtkCompositeDataSet | vtkDataObject): MultiBlockDataSet where to fill the attribute.
         attributeName (str): Attribute name.
         onPoints (bool, optional): True if attributes are on points, False if they are on cells.
             Defaults to False.
-        value (Any, optional): Filling value. It is recommended to use numpy scalar type for the values.
-            Defaults to:
+        listValues (list[Any], optional): List of filling value for each component.
+            Defaults to None, the filling value is for all components:
             -1 for int VTK arrays.
             0 for uint VTK arrays.
             nan for float VTK arrays.
@@ -98,40 +99,53 @@ def fillPartialAttributes(
 
     # Get information of the attribute to fill.
     vtkDataType: int = getVtkArrayTypeInMultiBlock( multiBlockDataSet, attributeName, onPoints )
-    infoAttributes: dict[ str, int ] = getAttributesWithNumberOfComponents( multiBlockDataSet, onPoints )
-    nbComponents: int = infoAttributes[ attributeName ]
+    nbComponents: int = getNumberOfComponentsMultiBlock( multiBlockDataSet, attributeName, onPoints )
     componentNames: tuple[ str, ...] = ()
     if nbComponents > 1:
         componentNames = getComponentNames( multiBlockDataSet, attributeName, onPoints )
 
+    typeMapping: dict[ int, type ] = vnp.get_vtk_to_numpy_typemap()
+    valueType: type = typeMapping[ vtkDataType ]
     # Set the default value depending of the type of the attribute to fill
-    if np.isnan( value ):
-        typeMapping: dict[ int, type ] = vnp.get_vtk_to_numpy_typemap()
-        valueType: type = typeMapping[ vtkDataType ]
+    if listValues is None:
+        defaultValue: Any
+        logger.warning( f"The attribute { attributeName } is filled with the default value for each component." )
         # Default value for float types is nan.
         if vtkDataType in ( VTK_FLOAT, VTK_DOUBLE ):
-            value = valueType( value )
+            defaultValue = valueType( np.nan )
             logger.warning(
-                f"{ attributeName } vtk data type is { vtkDataType } corresponding to { value.dtype } numpy type, default value is automatically set to nan."
+                f"{ attributeName } vtk data type is { vtkDataType } corresponding to { defaultValue.dtype } numpy type, default value is automatically set to nan."
             )
         # Default value for int types is -1.
         elif vtkDataType in ( VTK_CHAR, VTK_SIGNED_CHAR, VTK_SHORT, VTK_LONG, VTK_INT, VTK_LONG_LONG, VTK_ID_TYPE ):
-            value = valueType( -1 )
+            defaultValue = valueType( -1 )
             logger.warning(
-                f"{ attributeName } vtk data type is { vtkDataType } corresponding to { value.dtype } numpy type, default value is automatically set to -1."
+                f"{ attributeName } vtk data type is { vtkDataType } corresponding to { defaultValue.dtype } numpy type, default value is automatically set to -1."
             )
         # Default value for uint types is 0.
         elif vtkDataType in ( VTK_BIT, VTK_UNSIGNED_CHAR, VTK_UNSIGNED_SHORT, VTK_UNSIGNED_LONG, VTK_UNSIGNED_INT,
                               VTK_UNSIGNED_LONG_LONG ):
-            value = valueType( 0 )
+            defaultValue = valueType( 0 )
             logger.warning(
-                f"{ attributeName } vtk data type is { vtkDataType } corresponding to { value.dtype } numpy type, default value is automatically set to 0."
+                f"{ attributeName } vtk data type is { vtkDataType } corresponding to { defaultValue.dtype } numpy type, default value is automatically set to 0."
             )
         else:
             logger.error( f"The type of the attribute { attributeName } is not compatible with the function." )
             return False
 
-    values: list[ Any ] = [ value for _ in range( nbComponents ) ]
+        listValues = [ defaultValue ] * nbComponents
+
+    else:
+        if len( listValues ) != nbComponents:
+            return False
+
+        for idValue in range( nbComponents ):
+            value: Any = listValues[ idValue ]
+            if type( value ) is not valueType:
+                listValues[ idValue ] = valueType( listValues[ idValue ] )
+                logger.warning(
+                    f"The filling value { value } for the attribute { attributeName } has not the correct type, it is convert to the numpy scalar type { valueType().dtype }."
+                )
 
     # Parse the multiBlockDataSet to create and fill the attribute on blocks where it is not.
     iterator: vtkDataObjectTreeIterator = vtkDataObjectTreeIterator()
@@ -141,7 +155,7 @@ def fillPartialAttributes(
     while iterator.GetCurrentDataObject() is not None:
         dataSet: vtkDataSet = vtkDataSet.SafeDownCast( iterator.GetCurrentDataObject() )
         if not isAttributeInObjectDataSet( dataSet, attributeName, onPoints ) and \
-           not createConstantAttributeDataSet( dataSet, values, attributeName, componentNames, onPoints, vtkDataType, logger ):
+           not createConstantAttributeDataSet( dataSet, listValues, attributeName, componentNames, onPoints, vtkDataType, logger ):
             return False
 
         iterator.GoToNextItem()
@@ -172,7 +186,7 @@ def fillAllPartialAttributes(
         infoAttributes: dict[ str, int ] = getAttributesWithNumberOfComponents( multiBlockDataSet, onPoints )
         for attributeName in infoAttributes:
             if not isAttributeGlobal( multiBlockDataSet, attributeName, onPoints ) and \
-               not fillPartialAttributes( multiBlockDataSet, attributeName, onPoints, logger=logger ):
+               not fillPartialAttributes( multiBlockDataSet, attributeName, onPoints=onPoints, logger=logger ):
                 return False
 
     return True
@@ -384,7 +398,7 @@ def createConstantAttributeDataSet(
     if valueType in ( int, float ):
         npType: type = type( np.array( listValues )[ 0 ] )
         logger.warning(
-            f"During the creation of the constant attribute { attributeName }, values will be converted from { valueType } to { npType }."
+            f"During the creation of the constant attribute { attributeName }, values have been converted from { valueType } to { npType }."
         )
         logger.warning( "To avoid any issue with the conversion, please use directly numpy scalar type for the values" )
         valueType = npType

geos-mesh/tests/test_FillPartialArrays.py

@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright 2023-2024 TotalEnergies.
+# SPDX-FileContributor: Romain Baville
+# SPDX-License-Identifier: Apache 2.0
+# ruff: noqa: E402 # disable Module level import not at top of file
+# mypy: disable-error-code="operator"
+import pytest
+
+from typing import Any
+from vtkmodules.vtkCommonDataModel import vtkMultiBlockDataSet
+
+from geos.mesh.processing.FillPartialArrays import FillPartialArrays
+
+
+@pytest.mark.parametrize( "dictAttributesValues", [
+    ( {
+        "PORO": None
+    } ),
+    ( {
+        "PERM": None
+    } ),
+    ( {
+        "PORO": None,
+        "PERM": None
+    } ),
+    ( {
+        "PORO": [ 4 ]
+    } ),
+    ( {
+        "PERM": [ 4, 4, 4 ]
+    } ),
+    ( {
+        "PORO": [ 4 ],
+        "PERM": [ 4, 4, 4 ]
+    } ),
+    ( {
+        "PORO": None,
+        "PERM": [ 4, 4, 4 ]
+    } ),
+    ( {
+        "PORO": [ 4 ],
+        "PERM": None
+    } ),
+] )
+def test_FillPartialArrays(
+    dataSetTest: vtkMultiBlockDataSet,
+    dictAttributesValues: dict[ str, Any ],
+) -> None:
+    """Test FillPartialArrays vtk filter."""
+    multiBlockDataSet: vtkMultiBlockDataSet = dataSetTest( "multiblock" )
+
+    filter: FillPartialArrays = FillPartialArrays( multiBlockDataSet, dictAttributesValues )
+    assert filter.applyFilter()