ras-commander 0.48.0__py3-none-any.whl → 0.50.0__py3-none-any.whl

ras_commander/HdfMesh.py

@@ -1,11 +1,36 @@
 """
-Class: HdfMesh
-
-Attribution: A substantial amount of code in this file is sourced or derived 
-from the https://github.com/fema-ffrd/rashdf library, 
-released under MIT license and Copyright (c) 2024 fema-ffrd
-
-The file has been forked and modified for use in RAS Commander.
+A static class for handling mesh-related operations on HEC-RAS HDF files.
+
+This class provides static methods to extract and analyze mesh data from HEC-RAS HDF files,
+including mesh area names, mesh areas, cell polygons, cell points, cell faces, and
+2D flow area attributes. No instantiation is required to use these methods.
+
+All methods are designed to work with the mesh geometry data stored in
+HEC-RAS HDF files, providing functionality to retrieve and process various aspects
+of the 2D flow areas and their associated mesh structures.
+
+
+List of Functions:
+-----------------
+get_mesh_area_names()
+    Returns list of 2D mesh area names
+get_mesh_areas()
+    Returns 2D flow area perimeter polygons
+get_mesh_cell_polygons()
+    Returns 2D flow mesh cell polygons
+get_mesh_cell_points()
+    Returns 2D flow mesh cell center points
+get_mesh_cell_faces()
+    Returns 2D flow mesh cell faces
+get_mesh_area_attributes()
+    Returns geometry 2D flow area attributes
+get_mesh_face_property_tables()
+    Returns Face Property Tables for each Face in all 2D Flow Areas
+get_mesh_cell_property_tables()
+    Returns Cell Property Tables for each Cell in all 2D Flow Areas
+
+Each function is decorated with @standardize_input and @log_call for consistent
+input handling and logging functionality.
 """
 from pathlib import Path
 import h5py
@@ -44,9 +69,9 @@ class HdfMesh:
 
     @staticmethod
     @standardize_input(file_type='plan_hdf')
-    def mesh_area_names(hdf_path: Path) -> List[str]:
+    def get_mesh_area_names(hdf_path: Path) -> List[str]:
         """
-        Return a list of the 2D mesh area names of the RAS geometry.
+        Return a list of the 2D mesh area names from the RAS geometry.
 
         Parameters
         ----------
@@ -56,7 +81,8 @@ class HdfMesh:
         Returns
         -------
         List[str]
-            A list of the 2D mesh area names (str) within the RAS geometry if 2D areas exist.
+            A list of the 2D mesh area names within the RAS geometry.
+            Returns an empty list if no 2D areas exist or if there's an error.
         """
         try:
             with h5py.File(hdf_path, 'r') as hdf_file:
@@ -64,7 +90,7 @@ class HdfMesh:
                     return list()
                 return list(
                     [
-                        HdfUtils.convert_ras_hdf_string(n.decode('utf-8'))  # Decode as UTF-8
+                        HdfUtils.convert_ras_string(n.decode('utf-8'))
                         for n in hdf_file["Geometry/2D Flow Areas/Attributes"][()]["Name"]
                     ]
                 )
@@ -74,7 +100,7 @@ class HdfMesh:
 
     @staticmethod
     @standardize_input(file_type='geom_hdf')
-    def mesh_areas(hdf_path: Path) -> GeoDataFrame:
+    def get_mesh_areas(hdf_path: Path) -> GeoDataFrame:
         """
         Return 2D flow area perimeter polygons.
 
@@ -90,7 +116,7 @@ class HdfMesh:
         """
         try:
             with h5py.File(hdf_path, 'r') as hdf_file:
-                mesh_area_names = HdfMesh.mesh_area_names(hdf_path)
+                mesh_area_names = HdfMesh.get_mesh_area_names(hdf_path)
                 if not mesh_area_names:
                     return GeoDataFrame()
                 mesh_area_polygons = [
@@ -100,7 +126,7 @@ class HdfMesh:
                 return GeoDataFrame(
                     {"mesh_name": mesh_area_names, "geometry": mesh_area_polygons},
                     geometry="geometry",
-                    crs=HdfUtils.projection(hdf_file),  # Pass the h5py.File object instead of the path
+                    crs=HdfBase.get_projection(hdf_file),
                 )
         except Exception as e:
             logger.error(f"Error reading mesh areas from {hdf_path}: {str(e)}")
@@ -108,7 +134,7 @@ class HdfMesh:
 
     @staticmethod
     @standardize_input(file_type='geom_hdf')
-    def mesh_cell_polygons(hdf_path: Path) -> GeoDataFrame:
+    def get_mesh_cell_polygons(hdf_path: Path) -> GeoDataFrame:
         """
         Return 2D flow mesh cell polygons.
 
@@ -120,63 +146,64 @@ class HdfMesh:
         Returns
         -------
         GeoDataFrame
-            A GeoDataFrame containing the 2D flow mesh cell polygons.
+            A GeoDataFrame containing the 2D flow mesh cell polygons with columns:
+            - mesh_name: name of the mesh area
+            - cell_id: unique identifier for each cell
+            - geometry: polygon geometry of the cell
+            Returns an empty GeoDataFrame if no 2D areas exist or if there's an error.
         """
         try:
             with h5py.File(hdf_path, 'r') as hdf_file:
-                mesh_area_names = HdfMesh.mesh_area_names(hdf_path)
+                mesh_area_names = HdfMesh.get_mesh_area_names(hdf_path)
                 if not mesh_area_names:
                     return GeoDataFrame()
 
-                face_gdf = HdfMesh.mesh_cell_faces(hdf_path)
-
-                cell_dict = {"mesh_name": [], "cell_id": [], "geometry": []}
-                for i, mesh_name in enumerate(mesh_area_names):
-                    cell_cnt = hdf_file["Geometry/2D Flow Areas/Cell Info"][()][i][1]
-                    cell_ids = list(range(cell_cnt))
-                    cell_face_info = hdf_file[
-                        "Geometry/2D Flow Areas/{}/Cells Face and Orientation Info".format(mesh_name)
-                    ][()]
-                    cell_face_values = hdf_file[
-                        "Geometry/2D Flow Areas/{}/Cells Face and Orientation Values".format(mesh_name)
-                    ][()][:, 0]
-                    face_id_lists = list(
-                        np.vectorize(
-                            lambda cell_id: str(
-                                cell_face_values[
-                                    cell_face_info[cell_id][0] : cell_face_info[cell_id][0]
-                                    + cell_face_info[cell_id][1]
-                                ]
-                            )
-                        )(cell_ids)
-                    )
-                    mesh_faces = (
-                        face_gdf[face_gdf.mesh_name == mesh_name][["face_id", "geometry"]]
-                        .set_index("face_id")
-                        .to_numpy()
-                    )
-                    cell_dict["mesh_name"] += [mesh_name] * cell_cnt
-                    cell_dict["cell_id"] += cell_ids
-                    cell_dict["geometry"] += list(
-                        np.vectorize(
-                            lambda face_id_list: (
-                                lambda geom_col: Polygon(list(polygonize(geom_col))[0])
-                            )(
-                                np.ravel(
-                                    mesh_faces[
-                                        np.array(face_id_list.strip("[]").split()).astype(int)
-                                    ]
-                                )
-                            )
-                        )(face_id_lists)
-                    )
-                return GeoDataFrame(cell_dict, geometry="geometry", crs=HdfUtils.projection(hdf_file))
+                # Get face geometries once
+                face_gdf = HdfMesh.get_mesh_cell_faces(hdf_path)
+                
+                # Pre-allocate lists for better memory efficiency
+                all_mesh_names = []
+                all_cell_ids = []
+                all_geometries = []
+
+                for mesh_name in mesh_area_names:
+                    # Get cell face info in one read
+                    cell_face_info = hdf_file[f"Geometry/2D Flow Areas/{mesh_name}/Cells Face and Orientation Info"][()]
+                    cell_face_values = hdf_file[f"Geometry/2D Flow Areas/{mesh_name}/Cells Face and Orientation Values"][()][:, 0]
+                    
+                    # Create face lookup dictionary for this mesh
+                    mesh_faces_dict = dict(face_gdf[face_gdf.mesh_name == mesh_name][["face_id", "geometry"]].values)
+
+                    # Process each cell
+                    for cell_id, (start, length) in enumerate(cell_face_info[:, :2]):
+                        face_ids = cell_face_values[start:start + length]
+                        face_geoms = [mesh_faces_dict[face_id] for face_id in face_ids]
+                        
+                        # Create polygon
+                        polygons = list(polygonize(face_geoms))
+                        if polygons:
+                            all_mesh_names.append(mesh_name)
+                            all_cell_ids.append(cell_id)
+                            all_geometries.append(Polygon(polygons[0]))
+
+                # Create GeoDataFrame in one go
+                return GeoDataFrame(
+                    {
+                        "mesh_name": all_mesh_names,
+                        "cell_id": all_cell_ids,
+                        "geometry": all_geometries
+                    },
+                    geometry="geometry",
+                    crs=HdfBase.get_projection(hdf_file)
+                )
+
         except Exception as e:
             logger.error(f"Error reading mesh cell polygons from {hdf_path}: {str(e)}")
             return GeoDataFrame()
+        
     @staticmethod
     @standardize_input(file_type='plan_hdf')
-    def mesh_cell_points(hdf_path: Path) -> GeoDataFrame:
+    def get_mesh_cell_points(hdf_path: Path) -> GeoDataFrame:
         """
         Return 2D flow mesh cell center points.
 
@@ -192,30 +219,43 @@ class HdfMesh:
         """
         try:
             with h5py.File(hdf_path, 'r') as hdf_file:
-                mesh_area_names = HdfMesh.mesh_area_names(hdf_path)
+                mesh_area_names = HdfMesh.get_mesh_area_names(hdf_path)
                 if not mesh_area_names:
                     return GeoDataFrame()
                 
-                pnt_dict = {"mesh_name": [], "cell_id": [], "geometry": []}
+                # Pre-allocate lists
+                all_mesh_names = []
+                all_cell_ids = []
+                all_points = []
+
                 for mesh_name in mesh_area_names:
-                    cell_center_coords = hdf_file[f"Geometry/2D Flow Areas/{mesh_name}/Cells Center Coordinate"][()]
-                    cell_count = len(cell_center_coords)
+                    # Get all cell centers in one read
+                    cell_centers = hdf_file[f"Geometry/2D Flow Areas/{mesh_name}/Cells Center Coordinate"][()]
+                    cell_count = len(cell_centers)
                     
-                    pnt_dict["mesh_name"] += [mesh_name] * cell_count
-                    pnt_dict["cell_id"] += range(cell_count)
-                    pnt_dict["geometry"] += list(
-                        np.vectorize(lambda coords: Point(coords), signature="(n)->()")(
-                            cell_center_coords
-                        )
-                    )
-                return GeoDataFrame(pnt_dict, geometry="geometry", crs=HdfUtils.projection(hdf_path))
+                    # Extend lists efficiently
+                    all_mesh_names.extend([mesh_name] * cell_count)
+                    all_cell_ids.extend(range(cell_count))
+                    all_points.extend(Point(coords) for coords in cell_centers)
+
+                # Create GeoDataFrame in one go
+                return GeoDataFrame(
+                    {
+                        "mesh_name": all_mesh_names,
+                        "cell_id": all_cell_ids,
+                        "geometry": all_points
+                    },
+                    geometry="geometry",
+                    crs=HdfBase.get_projection(hdf_file)
+                )
+
         except Exception as e:
             logger.error(f"Error reading mesh cell points from {hdf_path}: {str(e)}")
             return GeoDataFrame()
 
     @staticmethod
     @standardize_input(file_type='plan_hdf')
-    def mesh_cell_faces(hdf_path: Path) -> GeoDataFrame:
+    def get_mesh_cell_faces(hdf_path: Path) -> GeoDataFrame:
         """
         Return 2D flow mesh cell faces.
 
@@ -231,45 +271,53 @@ class HdfMesh:
         """
         try:
             with h5py.File(hdf_path, 'r') as hdf_file:
-                mesh_area_names = HdfMesh.mesh_area_names(hdf_path)
+                mesh_area_names = HdfMesh.get_mesh_area_names(hdf_path)
                 if not mesh_area_names:
                     return GeoDataFrame()
-                face_dict = {"mesh_name": [], "face_id": [], "geometry": []}
+
+                # Pre-allocate lists
+                all_mesh_names = []
+                all_face_ids = []
+                all_geometries = []
+
                 for mesh_name in mesh_area_names:
-                    facepoints_index = hdf_file[
-                        "Geometry/2D Flow Areas/{}/Faces FacePoint Indexes".format(mesh_name)
-                    ][()]
-                    facepoints_coordinates = hdf_file[
-                        "Geometry/2D Flow Areas/{}/FacePoints Coordinate".format(mesh_name)
-                    ][()]
-                    faces_perimeter_info = hdf_file[
-                        "Geometry/2D Flow Areas/{}/Faces Perimeter Info".format(mesh_name)
-                    ][()]
-                    faces_perimeter_values = hdf_file[
-                        "Geometry/2D Flow Areas/{}/Faces Perimeter Values".format(mesh_name)
-                    ][()]
-                    face_id = -1
-                    for pnt_a_index, pnt_b_index in facepoints_index:
-                        face_id += 1
-                        face_dict["mesh_name"].append(mesh_name)
-                        face_dict["face_id"].append(face_id)
-                        coordinates = list()
-                        coordinates.append(facepoints_coordinates[pnt_a_index])
-                        starting_row, count = faces_perimeter_info[face_id]
+                    # Read all data at once
+                    facepoints_index = hdf_file[f"Geometry/2D Flow Areas/{mesh_name}/Faces FacePoint Indexes"][()]
+                    facepoints_coords = hdf_file[f"Geometry/2D Flow Areas/{mesh_name}/FacePoints Coordinate"][()]
+                    faces_perim_info = hdf_file[f"Geometry/2D Flow Areas/{mesh_name}/Faces Perimeter Info"][()]
+                    faces_perim_values = hdf_file[f"Geometry/2D Flow Areas/{mesh_name}/Faces Perimeter Values"][()]
+
+                    # Process each face
+                    for face_id, ((pnt_a_idx, pnt_b_idx), (start_row, count)) in enumerate(zip(facepoints_index, faces_perim_info)):
+                        coords = [facepoints_coords[pnt_a_idx]]
+                        
                         if count > 0:
-                            coordinates += list(
-                                faces_perimeter_values[starting_row : starting_row + count]
-                            )
-                        coordinates.append(facepoints_coordinates[pnt_b_index])
-                        face_dict["geometry"].append(LineString(coordinates))
-                return GeoDataFrame(face_dict, geometry="geometry", crs=HdfUtils.projection(hdf_path))
+                            coords.extend(faces_perim_values[start_row:start_row + count])
+                            
+                        coords.append(facepoints_coords[pnt_b_idx])
+                        
+                        all_mesh_names.append(mesh_name)
+                        all_face_ids.append(face_id)
+                        all_geometries.append(LineString(coords))
+
+                # Create GeoDataFrame in one go
+                return GeoDataFrame(
+                    {
+                        "mesh_name": all_mesh_names,
+                        "face_id": all_face_ids,
+                        "geometry": all_geometries
+                    },
+                    geometry="geometry",
+                    crs=HdfBase.get_projection(hdf_file)
+                )
+
         except Exception as e:
-            self.logger.error(f"Error reading mesh cell faces from {hdf_path}: {str(e)}")
+            logger.error(f"Error reading mesh cell faces from {hdf_path}: {str(e)}")
             return GeoDataFrame()
 
     @staticmethod
     @standardize_input(file_type='geom_hdf')
-    def get_geom_2d_flow_area_attrs(hdf_path: Path) -> Dict[str, Any]:
+    def get_mesh_area_attributes(hdf_path: Path) -> pd.DataFrame:
         """
         Return geometry 2D flow area attributes from a HEC-RAS HDF file.
 
@@ -280,8 +328,8 @@ class HdfMesh:
 
         Returns
         -------
-        Dict[str, Any]
-            A dictionary containing the 2D flow area attributes.
+        pd.DataFrame
+            A DataFrame containing the 2D flow area attributes.
         """
         try:
             with h5py.File(hdf_path, 'r') as hdf_file:
@@ -293,20 +341,20 @@ class HdfMesh:
                             value = d2_flow_area[name][()]
                             if isinstance(value, bytes):
                                 value = value.decode('utf-8')  # Decode as UTF-8
-                            result[name] = value
+                            result[name] = value if not isinstance(value, bytes) else value.decode('utf-8')
                         except Exception as e:
                             logger.warning(f"Error converting attribute '{name}': {str(e)}")
-                    return result
+                    return pd.DataFrame.from_dict(result, orient='index', columns=['Value'])
                 else:
                     logger.info("No 2D Flow Area attributes found or invalid dataset.")
-                    return {}
+                    return pd.DataFrame()  # Return an empty DataFrame
         except Exception as e:
             logger.error(f"Error reading 2D flow area attributes from {hdf_path}: {str(e)}")
-            return {}
+            return pd.DataFrame()  # Return an empty DataFrame
 
     @staticmethod
     @standardize_input(file_type='geom_hdf')
-    def get_face_property_tables(hdf_path: Path) -> Dict[str, pd.DataFrame]:
+    def get_mesh_face_property_tables(hdf_path: Path) -> Dict[str, pd.DataFrame]:
         """
         Extract Face Property Tables for each Face in all 2D Flow Areas.
 
@@ -318,12 +366,19 @@ class HdfMesh:
         Returns
         -------
         Dict[str, pd.DataFrame]
-            A dictionary where keys are mesh names and values are DataFrames
-            containing the Face Property Tables for all faces in that mesh.
+            A dictionary where:
+            - keys: mesh area names (str)
+            - values: DataFrames with columns:
+                - Face ID: unique identifier for each face
+                - Z: elevation
+                - Area: face area
+                - Wetted Perimeter: wetted perimeter length
+                - Manning's n: Manning's roughness coefficient
+            Returns an empty dictionary if no 2D areas exist or if there's an error.
         """
         try:
             with h5py.File(hdf_path, 'r') as hdf_file:
-                mesh_area_names = HdfMesh.mesh_area_names(hdf_path)
+                mesh_area_names = HdfMesh.get_mesh_area_names(hdf_path)
                 if not mesh_area_names:
                     return {}
 
@@ -351,3 +406,56 @@ class HdfMesh:
         except Exception as e:
             logger.error(f"Error extracting face property tables from {hdf_path}: {str(e)}")
             return {}
+
+    @staticmethod
+    @standardize_input(file_type='geom_hdf')
+    def get_mesh_cell_property_tables(hdf_path: Path) -> Dict[str, pd.DataFrame]:
+        """
+        Extract Cell Property Tables for each Cell in all 2D Flow Areas.
+
+        Parameters
+        ----------
+        hdf_path : Path
+            Path to the HEC-RAS geometry HDF file.
+
+        Returns
+        -------
+        Dict[str, pd.DataFrame]
+            A dictionary where:
+            - keys: mesh area names (str)
+            - values: DataFrames with columns:
+                - Cell ID: unique identifier for each cell
+                - Z: elevation
+                - Volume: cell volume
+                - Surface Area: cell surface area
+            Returns an empty dictionary if no 2D areas exist or if there's an error.
+        """
+        try:
+            with h5py.File(hdf_path, 'r') as hdf_file:
+                mesh_area_names = HdfMesh.get_mesh_area_names(hdf_path)
+                if not mesh_area_names:
+                    return {}
+
+                result = {}
+                for mesh_name in mesh_area_names:
+                    cell_elevation_info = hdf_file[f"Geometry/2D Flow Areas/{mesh_name}/Cells Elevation Volume Info"][()]
+                    cell_elevation_values = hdf_file[f"Geometry/2D Flow Areas/{mesh_name}/Cells Elevation Volume Values"][()]
+                    
+                    cell_data = []
+                    for cell_id, (start_index, count) in enumerate(cell_elevation_info):
+                        cell_values = cell_elevation_values[start_index:start_index+count]
+                        for z, volume, surface_area in cell_values:
+                            cell_data.append({
+                                'Cell ID': cell_id,
+                                'Z': str(z),
+                                'Volume': str(volume),
+                                'Surface Area': str(surface_area)
+                            })
+                    
+                    result[mesh_name] = pd.DataFrame(cell_data)
+                
+                return result
+
+        except Exception as e:
+            logger.error(f"Error extracting cell property tables from {hdf_path}: {str(e)}")
+            return {}