steer-core 0.1.16__py3-none-any.whl → 0.1.17__py3-none-any.whl

steer_core/Mixins/Colors.py

@@ -4,14 +4,16 @@ import plotly.colors as pc
 import pandas as pd
 import numpy as np
 
+
 class ColorMixin:
     """
     A class to manage colors, including conversion between hex and RGB formats,
     and generating color gradients.
     """
+
     @staticmethod
     def rgb_tuple_to_hex(rgb):
-        return '#{:02x}{:02x}{:02x}'.format(*rgb)
+        return "#{:02x}{:02x}{:02x}".format(*rgb)
 
     @staticmethod
     def get_colorway(color1, color2, n):
@@ -39,3 +41,185 @@ class ColorMixin:
 
         return colors
 
+    @staticmethod
+    def adjust_fill_opacity(color_str: str, opacity: float) -> str:
+        """
+        Adjust the fill opacity of any color format while preserving line opacity.
+
+        Parameters
+        ----------
+        color_str : str
+            Color in any format (hex, rgb, rgba, named)
+        opacity : float
+            Target opacity (0.0 to 1.0)
+
+        Returns
+        -------
+        str
+            Color string with adjusted opacity in rgba format
+        """
+        if not color_str:
+            return color_str
+
+        if "rgba" in color_str:
+            return ColorMixin._update_rgba_opacity(color_str, opacity)
+        elif "rgb" in color_str:
+            return color_str.replace("rgb(", "rgba(").replace(")", f", {opacity})")
+        elif color_str.startswith("#"):
+            return ColorMixin._hex_to_rgba(color_str, opacity)
+
+        # For named colors, try to convert or return as-is
+        return color_str
+
+    @staticmethod
+    def _hex_to_rgba(hex_color: str, opacity: float) -> str:
+        """
+        Convert hex color to rgba with specified opacity.
+
+        Parameters
+        ----------
+        hex_color : str
+            Hex color string (e.g., '#FF0000')
+        opacity : float
+            Target opacity (0.0 to 1.0)
+
+        Returns
+        -------
+        str
+            RGBA color string
+        """
+        hex_color = hex_color.lstrip("#")
+        if len(hex_color) == 6:
+            try:
+                r = int(hex_color[0:2], 16)
+                g = int(hex_color[2:4], 16)
+                b = int(hex_color[4:6], 16)
+                return f"rgba({r}, {g}, {b}, {opacity})"
+            except ValueError:
+                return hex_color
+        elif len(hex_color) == 3:
+            # Handle short hex format (#RGB -> #RRGGBB)
+            try:
+                r = int(hex_color[0] * 2, 16)
+                g = int(hex_color[1] * 2, 16)
+                b = int(hex_color[2] * 2, 16)
+                return f"rgba({r}, {g}, {b}, {opacity})"
+            except ValueError:
+                return hex_color
+
+        return hex_color
+
+    @staticmethod
+    def _update_rgba_opacity(rgba_str: str, opacity: float) -> str:
+        """
+        Update the opacity component of an existing rgba color string.
+
+        Parameters
+        ----------
+        rgba_str : str
+            Existing rgba color string (e.g., 'rgba(255, 0, 0, 0.5)')
+        opacity : float
+            New opacity value (0.0 to 1.0)
+
+        Returns
+        -------
+        str
+            Updated rgba color string
+        """
+        if "rgba(" not in rgba_str:
+            return rgba_str
+
+        try:
+            # Extract RGB components and replace alpha
+            rgb_part = rgba_str.split("rgba(")[1].rsplit(",", 1)[0]
+            return f"rgba({rgb_part}, {opacity})"
+        except (IndexError, ValueError):
+            return rgba_str
+
+    @staticmethod
+    def get_color_format(color_str: str) -> str:
+        """
+        Detect the format of a color string.
+
+        Parameters
+        ----------
+        color_str : str
+            Color string in any format
+
+        Returns
+        -------
+        str
+            Color format: 'hex', 'rgb', 'rgba', 'hsl', 'hsla', 'named', or 'unknown'
+        """
+        if not color_str or not isinstance(color_str, str):
+            return "unknown"
+
+        color_str = color_str.strip().lower()
+
+        if color_str.startswith("#"):
+            return "hex"
+        elif color_str.startswith("rgba("):
+            return "rgba"
+        elif color_str.startswith("rgb("):
+            return "rgb"
+        elif color_str.startswith("hsla("):
+            return "hsla"
+        elif color_str.startswith("hsl("):
+            return "hsl"
+        else:
+            return "named"  # Could be a named color like 'red', 'blue'
+
+    @staticmethod
+    def validate_opacity(opacity: float, param_name: str = "opacity") -> None:
+        """
+        Validate that opacity is within valid range.
+
+        Parameters
+        ----------
+        opacity : float
+            Opacity value to validate
+        param_name : str
+            Parameter name for error messages
+
+        Raises
+        ------
+        ValueError
+            If opacity is not between 0.0 and 1.0
+        """
+        if not isinstance(opacity, (int, float)):
+            raise ValueError(f"{param_name} must be a number, got {type(opacity)}")
+
+        if not (0.0 <= opacity <= 1.0):
+            raise ValueError(f"{param_name} must be between 0.0 and 1.0, got {opacity}")
+
+    @staticmethod
+    def adjust_trace_opacity(trace, opacity: float) -> None:
+        """
+        Adjust opacity of a plotly trace in-place.
+
+        Parameters
+        ----------
+        trace : plotly trace object
+            The trace to modify
+        opacity : float
+            Target opacity (0.0 to 1.0)
+        """
+        ColorMixin.validate_opacity(opacity)
+
+        # Adjust fill color if present
+        if hasattr(trace, "fillcolor") and trace.fillcolor:
+            trace.fillcolor = ColorMixin.adjust_fill_opacity(trace.fillcolor, opacity)
+
+        # Adjust marker color if present
+        if (
+            hasattr(trace, "marker")
+            and hasattr(trace.marker, "color")
+            and trace.marker.color
+        ):
+            trace.marker.color = ColorMixin.adjust_fill_opacity(
+                trace.marker.color, opacity
+            )
+
+        # Adjust line color if present (but maybe keep line opacity at 1.0?)
+        if hasattr(trace, "line") and hasattr(trace.line, "color") and trace.line.color:
+            trace.line.color = ColorMixin.adjust_fill_opacity(trace.line.color, opacity)

steer_core/Mixins/Coordinates.py

@@ -2,13 +2,17 @@ import numpy as np
 import pandas as pd
 from typing import Tuple
 
+
 class CoordinateMixin:
     """
     A class to manage and manipulate 3D coordinates.
     Provides methods for rotation, area calculation, and coordinate ordering.
     """
+
     @staticmethod
-    def rotate_coordinates(coords: np.ndarray, axis: str, angle: float, center: tuple = None) -> np.ndarray:
+    def rotate_coordinates(
+        coords: np.ndarray, axis: str, angle: float, center: tuple = None
+    ) -> np.ndarray:
         """
         Rotate a (N, 3) NumPy array of 3D coordinates around the specified axis.
         Can handle coordinates with None values (preserves None positions).
@@ -20,48 +24,64 @@ class CoordinateMixin:
         :return: Rotated NumPy array of shape (N, 3)
         """
         if coords.shape[1] != 3:
-            raise ValueError("Input array must have shape (N, 3) for x, y, z coordinates")
+            raise ValueError(
+                "Input array must have shape (N, 3) for x, y, z coordinates"
+            )
 
         # Validate center parameter
         if center is not None:
             if not isinstance(center, (tuple, list)) or len(center) != 3:
-                raise ValueError("Center must be a tuple or list of 3 coordinates (x, y, z)")
+                raise ValueError(
+                    "Center must be a tuple or list of 3 coordinates (x, y, z)"
+                )
             if not all(isinstance(coord, (int, float)) for coord in center):
                 raise TypeError("All center coordinates must be numbers")
             center = np.array(center, dtype=float)
 
         # Check if we have None values
-        has_nones = np.any(pd.isna(coords[:, 0])) if hasattr(pd, 'isna') else np.any(coords[:, 0] == None)
-        
+        has_nones = (
+            np.any(pd.isna(coords[:, 0]))
+            if hasattr(pd, "isna")
+            else np.any(coords[:, 0] == None)
+        )
+
         if has_nones:
             # Create a copy to preserve original
             result = coords.copy()
-            
+
             # Find non-None rows
-            x_is_none = pd.isna(coords[:, 0]) if hasattr(pd, 'isna') else (coords[:, 0] == None)
+            x_is_none = (
+                pd.isna(coords[:, 0]) if hasattr(pd, "isna") else (coords[:, 0] == None)
+            )
             valid_mask = ~x_is_none
-            
+
             if np.any(valid_mask):
                 # Extract valid coordinates and convert to float
                 valid_coords = coords[valid_mask].astype(float)
-                
+
                 # Apply rotation to valid coordinates
-                rotated_valid = CoordinateMixin._rotate_around_center(valid_coords, axis, angle, center)
-                
+                rotated_valid = CoordinateMixin._rotate_around_center(
+                    valid_coords, axis, angle, center
+                )
+
                 # Put rotated coordinates back in result
                 result[valid_mask] = rotated_valid
-                
+
             return result
-        
+
         else:
             # No None values - use rotation with center
-            return CoordinateMixin._rotate_around_center(coords.astype(float), axis, angle, center)
+            return CoordinateMixin._rotate_around_center(
+                coords.astype(float), axis, angle, center
+            )
 
     @staticmethod
-    def _rotate_around_center(coords: np.ndarray, axis: str, angle: float, center: np.ndarray = None) -> np.ndarray:
+    def _rotate_around_center(
+        coords: np.ndarray, axis: str, angle: float, center: np.ndarray = None
+    ) -> np.ndarray:
         """
         Rotate coordinates around a specified center point.
-        
+
         :param coords: NumPy array of shape (N, 3) with valid coordinates
         :param axis: Axis to rotate around ('x', 'y', or 'z')
         :param angle: Angle in degrees
@@ -71,18 +91,22 @@ class CoordinateMixin:
         if center is None:
             # Rotate around origin - use existing method
             return CoordinateMixin._rotate_valid_coordinates(coords, axis, angle)
-        
+
         # Translate coordinates to center at origin
         translated_coords = coords - center
-        
+
         # Rotate around origin
-        rotated_coords = CoordinateMixin._rotate_valid_coordinates(translated_coords, axis, angle)
-        
+        rotated_coords = CoordinateMixin._rotate_valid_coordinates(
+            translated_coords, axis, angle
+        )
+
         # Translate back to original position
         return rotated_coords + center
 
     @staticmethod
-    def build_square_array(x: float, y: float, x_width: float, y_width: float) -> Tuple[np.ndarray, np.ndarray]:
+    def build_square_array(
+        x: float, y: float, x_width: float, y_width: float
+    ) -> Tuple[np.ndarray, np.ndarray]:
         """
         Build a NumPy array representing a square or rectangle defined by its bottom-left corner (x, y)
         and its width and height.
@@ -103,8 +127,7 @@ class CoordinateMixin:
         return x_coords, y_coords
 
     @staticmethod
-    def order_coordinates_clockwise(df: pd.DataFrame, plane='xy') -> pd.DataFrame:
-
+    def order_coordinates_clockwise(df: pd.DataFrame, plane="xy") -> pd.DataFrame:
         axis_1 = plane[0]
         axis_2 = plane[1]
 
@@ -113,13 +136,17 @@ class CoordinateMixin:
 
         angles = np.arctan2(df[axis_2] - cy, df[axis_1] - cx)
 
-        df['angle'] = angles
-        df_sorted = df.sort_values(by='angle').drop(columns='angle').reset_index(drop=True)
+        df["angle"] = angles
+        df_sorted = (
+            df.sort_values(by="angle").drop(columns="angle").reset_index(drop=True)
+        )
 
         return df_sorted
 
-    @staticmethod    
-    def _rotate_valid_coordinates(coords: np.ndarray, axis: str, angle: float) -> np.ndarray:
+    @staticmethod
+    def _rotate_valid_coordinates(
+        coords: np.ndarray, axis: str, angle: float
+    ) -> np.ndarray:
         """
         Rotate coordinates without None values using rotation matrices.
         """
@@ -127,35 +154,31 @@ class CoordinateMixin:
         cos_a = np.cos(angle_rad)
         sin_a = np.sin(angle_rad)
 
-        if axis == 'x':
-            R = np.array([[1, 0, 0],
-                        [0, cos_a, -sin_a],
-                        [0, sin_a, cos_a]])
-        elif axis == 'y':
-            R = np.array([[cos_a, 0, sin_a],
-                        [0, 1, 0],
-                        [-sin_a, 0, cos_a]])
-        elif axis == 'z':
-            R = np.array([[cos_a, -sin_a, 0],
-                        [sin_a, cos_a, 0],
-                        [0, 0, 1]])
+        if axis == "x":
+            R = np.array([[1, 0, 0], [0, cos_a, -sin_a], [0, sin_a, cos_a]])
+        elif axis == "y":
+            R = np.array([[cos_a, 0, sin_a], [0, 1, 0], [-sin_a, 0, cos_a]])
+        elif axis == "z":
+            R = np.array([[cos_a, -sin_a, 0], [sin_a, cos_a, 0], [0, 0, 1]])
         else:
             raise ValueError("Axis must be 'x', 'y', or 'z'.")
 
         return coords @ R.T
-    
+
     @staticmethod
     def _calculate_single_area(x: np.ndarray, y: np.ndarray) -> float:
         """
         Calculate the area of a single closed shape using the shoelace formula.
         """
         if len(x) < 3 or len(y) < 3:
-            raise ValueError("Trace must contain at least 3 points to form a closed shape.")
-        
+            raise ValueError(
+                "Trace must contain at least 3 points to form a closed shape."
+            )
+
         # Convert to float arrays to avoid object dtype issues
         x = np.asarray(x, dtype=float)
         y = np.asarray(y, dtype=float)
-        
+
         # Ensure the shape is closed by appending the first point to the end
         if (x[0], y[0]) != (x[-1], y[-1]):
             x = np.append(x, x[0])
@@ -165,7 +188,7 @@ class CoordinateMixin:
         area = 0.5 * np.abs(np.dot(x[:-1], y[1:]) - np.dot(y[:-1], x[1:]))
 
         return float(area)
-    
+
     @staticmethod
     def get_area_from_points(x: np.ndarray, y: np.ndarray) -> float:
         """
@@ -175,31 +198,33 @@ class CoordinateMixin:
         # Convert to numpy arrays and handle object dtype
         x = np.asarray(x)
         y = np.asarray(y)
-        
+
         # Check if we have None values (multiple shapes)
-        x_is_none = pd.isna(x) if hasattr(pd, 'isna') else (x == None)
-        
+        x_is_none = pd.isna(x) if hasattr(pd, "isna") else (x == None)
+
         if np.any(x_is_none):
             total_area = 0.0
-            
+
             # Find None indices to split the shapes
             none_indices = np.where(x_is_none)[0]
             start_idx = 0
-            
+
             # Process each shape segment
             for none_idx in none_indices:
                 if none_idx > start_idx:
                     # Extract segment coordinates
                     segment_x = x[start_idx:none_idx]
                     segment_y = y[start_idx:none_idx]
-                    
+
                     # Calculate area for this segment if it has enough points
                     if len(segment_x) >= 3:
-                        area = CoordinateMixin._calculate_single_area(segment_x, segment_y)
+                        area = CoordinateMixin._calculate_single_area(
+                            segment_x, segment_y
+                        )
                         total_area += area
-                        
+
                 start_idx = none_idx + 1
-            
+
             # Handle the last segment if it exists
             if start_idx < len(x):
                 segment_x = x[start_idx:]
@@ -207,25 +232,17 @@ class CoordinateMixin:
                 if len(segment_x) >= 3:
                     area = CoordinateMixin._calculate_single_area(segment_x, segment_y)
                     total_area += area
-                    
+
             return total_area
-        
+
         else:
             # Single shape - use original logic
             return CoordinateMixin._calculate_single_area(x, y)
 
     @staticmethod
     def extrude_footprint(
-            x: np.ndarray, 
-            y: np.ndarray,
-            datum: np.ndarray,
-            thickness: float
-        ) -> Tuple[
-            np.ndarray, 
-            np.ndarray, 
-            np.ndarray, 
-            np.ndarray
-        ]:
+        x: np.ndarray, y: np.ndarray, datum: np.ndarray, thickness: float
+    ) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
         """
         Extrude the 2D footprint to 3D and label each point with its side ('a' or 'b'), with 'a' being the top side and 'b' the bottom side.
 
@@ -252,31 +269,31 @@ class CoordinateMixin:
         x_full = np.concatenate([x, x])
         y_full = np.concatenate([y, y])
         z_full = np.concatenate([np.full_like(x, z_a), np.full_like(x, z_b)])
-        side_full = np.array(['a'] * len(x) + ['b'] * len(x))
+        side_full = np.array(["a"] * len(x) + ["b"] * len(x))
 
         return x_full, y_full, z_full, side_full
-    
+
     @staticmethod
     def remove_skip_coat_area(
-        x_coords: np.ndarray, 
-        y_coords: np.ndarray, 
-        weld_tab_positions: np.ndarray, 
-        skip_coat_width: float
+        x_coords: np.ndarray,
+        y_coords: np.ndarray,
+        weld_tab_positions: np.ndarray,
+        skip_coat_width: float,
     ) -> Tuple[np.ndarray, np.ndarray]:
         """
         Remove skip coat areas around weld tab positions from coordinates.
-        
+
         Parameters
         ----------
         x_coords : np.ndarray
             Array of x coordinates defining the boundary
-        y_coords : np.ndarray  
+        y_coords : np.ndarray
             Array of y coordinates defining the boundary
         weld_tab_positions : np.ndarray
             Array of x positions where weld tabs are located
         skip_coat_width : float
             Width of the skip coat area around each weld tab
-            
+
         Returns
         -------
         Tuple[np.ndarray, np.ndarray]
@@ -284,55 +301,61 @@ class CoordinateMixin:
         """
         if len(x_coords) == 0 or len(y_coords) == 0:
             return np.array([], dtype=float), np.array([], dtype=float)
-        
+
         x_min, x_max = np.min(x_coords), np.max(x_coords)
         y_min, y_max = np.min(y_coords), np.max(y_coords)
-        
+
         # Filter weld tab positions to only include those within bounds
         valid_positions = weld_tab_positions[
-            (weld_tab_positions + skip_coat_width >= x_min) & (weld_tab_positions - skip_coat_width <= x_max)
+            (weld_tab_positions + skip_coat_width >= x_min)
+            & (weld_tab_positions - skip_coat_width <= x_max)
         ]
-        
+
         # If no valid positions, return original rectangle
         if len(valid_positions) == 0:
             rect_x = [x_min, x_max, x_max, x_min, x_min]
             rect_y = [y_min, y_min, y_max, y_max, y_min]
             return np.array(rect_x, dtype=float), np.array(rect_y, dtype=float)
-        
+
         # Sort weld tab cut positions
         cuts = np.sort(valid_positions)
         half_width = skip_coat_width / 2
-        
+
         # Build kept horizontal segments by removing [cut - half, cut + half] around each cut
         segments = []
         start = x_min
-        
+
         for cut in cuts:
             end = cut - half_width
             if end > start:
                 segments.append((start, end))
             start = cut + half_width
-        
+
         # Add final segment if there's remaining space
         if start < x_max:
             segments.append((start, x_max))
-        
+
         # Build rectangles for each kept segment with np.nan separators
         x_result = []
         y_result = []
-        
+
         for i, (segment_start, segment_end) in enumerate(segments):
             # Create rectangle coordinates: bottom-left -> bottom-right -> top-right -> top-left -> close
-            rect_x = [segment_start, segment_end, segment_end, segment_start, segment_start]
+            rect_x = [
+                segment_start,
+                segment_end,
+                segment_end,
+                segment_start,
+                segment_start,
+            ]
             rect_y = [y_min, y_min, y_max, y_max, y_min]
-            
+
             x_result.extend(rect_x)
             y_result.extend(rect_y)
-            
+
             # Add np.nan separator (except for the last segment)
             if i < len(segments) - 1:  # Fixed: use index comparison
                 x_result.append(np.nan)
                 y_result.append(np.nan)
-        
-        return np.array(x_result, dtype=float), np.array(y_result, dtype=float)
 
+        return np.array(x_result, dtype=float), np.array(y_result, dtype=float)

steer_core/Mixins/Data.py

@@ -7,6 +7,7 @@ class DataMixin:
     A mixin class to handle data processing and validation for electrode materials.
     Provides methods to calculate properties, check curve directions, and process half-cell curves.
     """
+
     @staticmethod
     def enforce_monotonicity(array: np.ndarray) -> np.ndarray:
         """
@@ -37,4 +38,3 @@ class DataMixin:
             new_array = np.minimum.accumulate(new_array)
 
         return new_array
-