luminarycloud 0.22.0__py3-none-any.whl → 0.22.2__py3-none-any.whl

luminarycloud/vis/filters.py

@@ -139,6 +139,101 @@ class Slice(Filter):
         self.plane._from_proto(filter.slice.plane)
 
 
+class MultiSlice(Filter):
+    """
+    Creates multiple parallel slice planes between two positions.
+    Primarily useful as a convenience wrapper when combined with child filters like Threshold, avoiding manual slice filter loops.
+
+    .. warning:: This feature is experimental and may change or be removed in the future.
+
+    Attributes:
+    -----------
+    start_position : Vector3Like
+        The position of the first slice plane.
+    end_position : Vector3Like
+        The position of the last slice plane.
+    n_slices : int
+        The number of slice planes to create between start and end positions.
+    name : str
+        A user provided name for the filter.
+    project_vectors: bool
+        When true, vector fields will be projected onto the plane of each slice. This is often
+        useful for visualizing vector fields by removing the vector components in the normal
+        direction of the planes. Default: False
+    display_attrs : DisplayAttributes
+        Specifies this filter's appearance.
+    """
+
+    def __init__(self, name: str = "") -> None:
+        super().__init__(generate_id("multi-slice-"))
+        self._start_position: Vector3Like = Vector3(x=0, y=0, z=0)
+        self._end_position: Vector3Like = Vector3(x=1, y=0, z=0)
+        self._n_slices: int = 10
+        self._project_vectors: bool = False
+        self.name = name
+
+    @property
+    def start_position(self) -> Vector3Like:
+        return self._start_position
+
+    @start_position.setter
+    def start_position(self, new_start_position: Vector3Like) -> None:
+        self._start_position = _to_vector3(new_start_position)
+
+    @property
+    def end_position(self) -> Vector3Like:
+        return self._end_position
+
+    @end_position.setter
+    def end_position(self, new_end_position: Vector3Like) -> None:
+        self._end_position = _to_vector3(new_end_position)
+
+    @property
+    def n_slices(self) -> int:
+        return self._n_slices
+
+    @n_slices.setter
+    def n_slices(self, new_n_slices: int) -> None:
+        if not isinstance(new_n_slices, int):
+            raise TypeError(f"Expected 'int', got {type(new_n_slices).__name__}")
+        if new_n_slices < 2:
+            raise ValueError("n_slices must be at least 2")
+        self._n_slices = new_n_slices
+
+    @property
+    def project_vectors(self) -> bool:
+        return self._project_vectors
+
+    @project_vectors.setter
+    def project_vectors(self, new_project_vectors: bool) -> None:
+        if not isinstance(new_project_vectors, bool):
+            raise TypeError(f"Expected 'bool', got {type(new_project_vectors).__name__}")
+        self._project_vectors = new_project_vectors
+
+    def _to_proto(self) -> vis_pb2.Filter:
+        vis_filter = vis_pb2.Filter()
+        vis_filter.id = self.id
+        vis_filter.name = self.name
+        vis_filter.multi_slice.start_position.CopyFrom(_to_vector3(self.start_position)._to_proto())
+        vis_filter.multi_slice.end_position.CopyFrom(_to_vector3(self.end_position)._to_proto())
+        vis_filter.multi_slice.n_slices = self.n_slices
+        vis_filter.multi_slice.project_vectors = self.project_vectors
+        return vis_filter
+
+    def _from_proto(self, filter: vis_pb2.Filter) -> None:
+        typ = filter.WhichOneof("value")
+        if typ != "multi_slice":
+            raise TypeError(f"Expected 'multi_slice', got {typ}")
+        self.id = filter.id
+        self.name = filter.name
+        self.start_position = Vector3()
+        self.start_position._from_proto(filter.multi_slice.start_position)
+        self.end_position = Vector3()
+        self.end_position._from_proto(filter.multi_slice.end_position)
+        self.n_slices = filter.multi_slice.n_slices
+        self.project_vectors = filter.multi_slice.project_vectors
+
+
 class Isosurface(Filter):
     """
     Isosurface is used to evaluate scalar fields at constant values, known as
@@ -1130,6 +1225,8 @@ def _filter_to_obj_name(filter: Filter) -> str:
         raise TypeError(f"Expected 'Filter', got {type(filter).__name__}")
     if isinstance(filter, Slice):
         return "slice"
+    elif isinstance(filter, MultiSlice):
+        return "multi_slice"
     elif isinstance(filter, Isosurface):
         return "isosurface"
     elif isinstance(filter, PlaneClip):

luminarycloud/vis/interactive_report.py

@@ -1,6 +1,7 @@
 import io
+import numpy as np
 from .visualization import RenderOutput
-from .report import ReportEntry
+from .report import ReportEntry, ReportContext
 
 try:
     import luminarycloud_jupyter as lcj
@@ -8,6 +9,82 @@ except ImportError:
     lcj = None
 
 
+def _detect_outliers(
+    metadata: list[dict[str, str | float]],
+    output_fields: list[str],
+    percentile_threshold: float = 95.0,
+) -> list[int] | None:
+    """
+    Detect outliers using Mahalanobis distance.
+
+    Parameters
+    ----------
+    metadata : list[dict[str, str | float]]
+        List of metadata dictionaries for each row
+    output_fields : list[str]
+        List of output field names to use for outlier detection
+    percentile_threshold : float, optional
+        Percentile threshold for outlier detection (default: 95.0)
+
+    Returns
+    -------
+    list[int] | None
+        List of row indices that are outliers, or None if detection fails
+    """
+    # Need at least 2 fields for meaningful multivariate analysis
+    if len(output_fields) < 2:
+        return None
+
+    # Extract data for the specified output fields
+    try:
+        data = []
+        for row_metadata in metadata:
+            row_data = []
+            for field in output_fields:
+                value = row_metadata.get(field)
+                if value is None or isinstance(value, str):
+                    # Skip if field is missing or non-numeric
+                    return None
+                row_data.append(float(value))
+            data.append(row_data)
+
+        data_array = np.array(data)
+
+        # Need at least as many samples as dimensions for covariance matrix
+        if len(data_array) < len(output_fields):
+            return None
+
+        # Calculate mean and covariance matrix
+        mean_vec = np.mean(data_array, axis=0)
+        cov_matrix = np.cov(data_array.T)
+
+        # Check if covariance matrix is singular
+        if np.linalg.det(cov_matrix) == 0:
+            return None
+
+        # Invert covariance matrix
+        inv_cov_matrix = np.linalg.inv(cov_matrix)
+
+        # Calculate Mahalanobis distance for each point
+        distances = []
+        for point in data_array:
+            diff = point - mean_vec
+            distance = np.sqrt(diff @ inv_cov_matrix @ diff)
+            distances.append(distance)
+
+        # Determine outlier threshold using percentile
+        threshold = np.percentile(distances, percentile_threshold)
+
+        # Find outlier indices
+        outlier_indices = [i for i, d in enumerate(distances) if d > threshold]
+
+        return outlier_indices
+
+    except Exception:
+        # If anything goes wrong, return None (no outliers detected)
+        return None
+
+
 class InteractiveReport:
     """
     Interactive report widget with lazy loading for large datasets.
@@ -29,7 +106,7 @@ class InteractiveReport:
     # TODO Will/Matt: this list of report entries could be how we store stuff in the DB
     # for interactive reports, to reference the post proc. extracts. A report is essentially
     # a bunch of extracts + metadata.
-    def __init__(self, entries: list[ReportEntry]) -> None:
+    def __init__(self, entries: list[ReportEntry], context: ReportContext | None = None) -> None:
         if not lcj:
             raise ImportError("InteractiveScene requires luminarycloud[jupyter] to be installed")
 
@@ -37,6 +114,13 @@ class InteractiveReport:
         if len(self.entries) == 0:
             raise ValueError("Invalid number of entries, must be > 0")
 
+        # Validate and store context if provided
+        if context is not None:
+            self._validate_context(context)
+            self.context = context
+        else:
+            self.context = None
+
         # Determine grid dimensions by downloading first entry
         # to understand the structure (number of columns)
         first_entry = self.entries[0]
@@ -54,12 +138,55 @@ class InteractiveReport:
 
         nrows = len(self.entries)
 
+        # Prepare report context for the widget
+        context_dict = None
+        if self.context is not None:
+            context_dict = self.context.to_dict()
+
+            # Compute outlier indices if we have outputs
+            if self.context.outputs and len(self.context.outputs) >= 2:
+                outlier_indices = _detect_outliers(
+                    [re._metadata for re in self.entries], self.context.outputs
+                )
+                if outlier_indices is not None:
+                    context_dict["outlier_indices"] = outlier_indices
+
         # Create widget with metadata but without data
-        self.widget = lcj.EnsembleWidget([re._metadata for re in self.entries], nrows, ncols)
+        self.widget = lcj.EnsembleWidget(
+            [re._metadata for re in self.entries], nrows, ncols, report_context=context_dict
+        )
 
         # Set the callback for lazy loading row data
         self.widget.set_row_data_callback(self._load_row_data)
 
+    def _validate_context(self, context: ReportContext) -> None:
+        """
+        Validate that all inputs and outputs from the ReportContext exist in the
+        first report entry's metadata.
+
+        Raises:
+        -------
+        ValueError
+            If any inputs or outputs are missing from the first entry's metadata.
+        """
+        first_entry = self.entries[0]
+        metadata_keys = set(first_entry._metadata.keys())
+
+        # Check for missing inputs
+        missing_inputs = [key for key in context.inputs if key not in metadata_keys]
+
+        # Check for missing outputs
+        missing_outputs = [key for key in context.outputs if key not in metadata_keys]
+
+        # Raise exception if any keys are missing
+        if missing_inputs or missing_outputs:
+            error_parts = []
+            if missing_inputs:
+                error_parts.append(f"Missing inputs: {missing_inputs}")
+            if missing_outputs:
+                error_parts.append(f"Missing outputs: {missing_outputs}")
+            raise ValueError(f"ReportContext validation failed. {', '.join(error_parts)}")
+
     def _load_row_data(self, row: int) -> None:
         """
         Load and send data for a specific row to the widget.
@@ -79,11 +206,29 @@ class InteractiveReport:
                 image_and_label = extract.download_images()
                 # Each image gets its own column
                 for il in image_and_label:
-                    self.widget.set_cell_data(row, col, il[0].getvalue(), "jpg")
+                    # il is a tuple of (BytesIO, label)
+                    # Use camera label for the name, fallback to "image" if empty
+                    camera_label = il[1]
+                    name = camera_label if camera_label else "image"
+                    # For description: prefer extract.description, then camera label, then fallback message
+                    description = (
+                        extract.description
+                        if extract.description
+                        else camera_label if camera_label else "no label or description provided"
+                    )
+                    self.widget.set_cell_data(
+                        row,
+                        col,
+                        il[0].getvalue(),
+                        "jpg",
+                        name=name,
+                        description=description,
+                    )
                     col += 1
             else:
                 plot_data = extract.download_data()
-                data = plot_data[0][0]
+                data = plot_data[0][0]  # The CSV data (rows)
+                plot_label = plot_data[0][1]  # The label from the extract
                 all_axis_labels = data[0]
 
                 axis_data = []
@@ -91,14 +236,25 @@ class InteractiveReport:
                     axis_values = [row[axis_idx] for row in data[1:]]
                     axis_data.append(axis_values)
 
+                # For plots: use extract.name, then plot_label, then "plot" as fallback
+                # For description: use extract.description, fallback to message if empty
+                name = extract.name if extract.name else (plot_label if plot_label else "plot")
+                description = (
+                    extract.description
+                    if extract.description
+                    else "no label or description provided"
+                )
+
                 self.widget.set_cell_scatter_plot(
                     row,
                     col,
-                    f"Row #{row} - Multi-axis Plot",
+                    name,  # Use the same name for the plot title
                     all_axis_labels,
                     axis_data,
-                    plot_name=f"plot-{row}",
+                    plot_name=name,
                     plot_mode="markers",
+                    name=name,
+                    description=description,
                 )
                 col += 1
 

luminarycloud/vis/report.py

@@ -1,3 +1,4 @@
+import csv as csv_module
 import json
 import os
 from typing import TYPE_CHECKING
@@ -17,6 +18,79 @@ if TYPE_CHECKING:
     from .interactive_report import InteractiveReport
 
 
+class ReportContext:
+    """
+    Context for interactive reports that defines input and output metadata keys.
+    Inputs define what the geometric and flow conditions are varied with running
+    data generation and the outputs define what quantities are extracted from
+    the simulations. For the report context to be valid we require that the both
+    the inputs and outputs are non-empty.
+
+    Attributes:
+    -----------
+    inputs : list[str]
+        List of metadata keys (column names) that represent inputs to the report.
+    outputs : list[str]
+        List of metadata keys (column names) that represent outputs from the report.
+    """
+
+    def __init__(self, inputs: list[str], outputs: list[str]) -> None:
+        self.inputs = inputs
+        self.outputs = outputs
+
+    def to_dict(self) -> dict:
+        """Convert ReportContext to a dictionary for serialization."""
+        return {
+            "inputs": self.inputs,
+            "outputs": self.outputs,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ReportContext":
+        """Create a ReportContext from a dictionary.
+
+        Parameters:
+        -----------
+        data : dict
+            Dictionary containing 'inputs' and 'outputs' keys.
+
+        Raises:
+        -------
+        ValueError
+            If 'inputs' or 'outputs' keys are missing from the data.
+        """
+        if "inputs" not in data:
+            raise ValueError("ReportContext.from_dict: missing required key 'inputs'")
+        if "outputs" not in data:
+            raise ValueError("ReportContext.from_dict: missing required key 'outputs'")
+
+        inputs = data["inputs"]
+        outputs = data["outputs"]
+
+        if not isinstance(inputs, list):
+            raise ValueError(
+                f"ReportContext.from_dict: 'inputs' must be a list, got {type(inputs).__name__}"
+            )
+        if not isinstance(outputs, list):
+            raise ValueError(
+                f"ReportContext.from_dict: 'outputs' must be a list, got {type(outputs).__name__}"
+            )
+
+        if len(inputs) == 0:
+            raise ValueError("ReportContext.from_dict: 'inputs' must be non-empty")
+        if len(outputs) == 0:
+            raise ValueError("ReportContext.from_dict: 'outputs' must be non-empty")
+
+        return cls(inputs=inputs, outputs=outputs)
+
+
+def load_report_context_from_json(filepath: str) -> ReportContext:
+    """Load a ReportContext object from a JSON file at the given file path."""
+    with open(filepath, "r") as f:
+        data = json.load(f)
+    return ReportContext.from_dict(data)
+
+
 # TODO Will/Matt: this could be something like what we store in the DB
 # A report can contain a list of report entries that reference post proc.
 # extracts + styling info for how they should be displayed
@@ -86,7 +160,7 @@ class ReportEntry:
                 if res.HasField("line_data")
                 else RenderOutput(_InternalToken())
             )
-            extract._set_data(eid, self._project_id, eid, eid, status)
+            extract._set_data(eid, self._project_id, "", "", status)
             self._extracts.append(extract)
 
 
@@ -250,3 +324,41 @@ def load_report_from_json(filepath: str) -> "Report":
     with open(filepath, "r") as f:
         data = json.load(f)
     return Report.from_dict(data)
+
+
+def load_report_from_csv(filepath: str) -> "Report":
+    """Load a Report object from a CSV file at the given file path.
+
+    Each row in the CSV corresponds to a ReportEntry. Each column is converted
+    to metadata. No extracts are created when loading from CSV.
+
+    Parameters
+    ----------
+    filepath : str
+        Path to the CSV file to load.
+
+    Returns
+    -------
+    Report
+        A Report object with entries populated from the CSV rows.
+    """
+    entries = []
+    with open(filepath, "r") as f:
+        reader = csv_module.DictReader(f)
+        for row in reader:
+            # Convert all columns to metadata
+            metadata: dict[str, str | float] = {}
+            for key, value in row.items():
+                # Try to convert to float, otherwise keep as string
+                try:
+                    metadata[key] = float(value)
+                except (ValueError, TypeError):
+                    metadata[key] = value
+
+            # Create ReportEntry with placeholder project_id and no extracts
+            # We only need the project id for loading extracts, so we can omit it for CSV
+            # imports.
+            entry = ReportEntry(project_id="p-placeholder", extract_ids=[], metadata=metadata)
+            entries.append(entry)
+
+    return Report(entries)

luminarycloud/vis/visualization.py

@@ -38,6 +38,7 @@ from .filters import (
     Filter,
     PlaneClip,
     Slice,
+    MultiSlice,
     SurfaceStreamlines,
     SurfaceLIC,
     Threshold,
@@ -1282,6 +1283,8 @@ def _spec_to_scene(spec: vis_pb2.ExtractSpec) -> Scene:
                 pfilter = PlaneClip("")
         elif typ == "slice":
             pfilter = Slice("")
+        elif typ == "multi_slice":
+            pfilter = MultiSlice("")
         elif typ == "streamlines":
             s_typ = filter.streamlines.WhichOneof("seed_type")
             if s_typ == "surface":

luminarycloud/volume_selection.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 
 import logging
 from os import PathLike
-from typing import TYPE_CHECKING, Iterable, Iterator, Optional
+from typing import TYPE_CHECKING, Iterable, Iterator, Optional, Sequence
 from uuid import uuid4
 
 from luminarycloud._helpers import util
@@ -69,7 +69,7 @@ class VolumeSelection:
     >>> s.subtract(b)
     """
 
-    def __init__(self, geometry: "Geometry", volumes: list[Volume | int]):
+    def __init__(self, geometry: "Geometry", volumes: Sequence[Volume | int]):
         self.__geometry = geometry
         self.__volume_ids = set()
         for v in volumes:
@@ -583,6 +583,7 @@ class VolumeSelection:
         self,
         vector: Vector3Like,
         quantity: int,
+        symmetric: bool = False,
         *,
         feature_name: str = "Linear Pattern",
     ) -> None:
@@ -595,6 +596,8 @@ class VolumeSelection:
             The vector to repeat the selected volumes along.
         quantity : int
             The number of times to repeat the selected volumes.
+        symmetric : bool, default False
+            Whether the pattern is symmetric.
         feature_name : str
             The name of the feature.
         """
@@ -608,6 +611,7 @@ class VolumeSelection:
                             vector=_to_vector3_ad_proto(vector),
                         ),
                         quantity=quantity,
+                        symmetric=symmetric,
                     ),
                 ),
             )
@@ -618,6 +622,7 @@ class VolumeSelection:
         vector: Vector3Like,
         magnitude: float,
         quantity: int,
+        symmetric: bool = False,
         *,
         feature_name: str = "Linear Pattern",
     ) -> None:
@@ -633,12 +638,15 @@ class VolumeSelection:
             The magnitude of the vector.
         quantity : int
             The number of times to repeat the selected volumes.
+        symmetric : bool, default False
+            Whether the pattern is symmetric.
         feature_name : str
             The name of the feature.
         """
         return self.linear_pattern(
             vector=[vector[i] * magnitude for i in range(3)],
             quantity=quantity,
+            symmetric=symmetric,
             feature_name=feature_name,
         )
 
@@ -719,17 +727,17 @@ class VolumeSelection:
 
         params = gpb.Create()
         if isinstance(shape, Sphere):
-            params.sphere.CopyFrom(shape._to_proto())  # type: ignore
+            params.sphere.CopyFrom(shape._to_proto())
         elif isinstance(shape, Cube):
-            params.box.CopyFrom(shape._to_proto())  # type: ignore
+            params.box.CopyFrom(shape._to_proto())
         elif isinstance(shape, Cylinder):
-            params.cylinder.CopyFrom(shape._to_proto())  # type: ignore
+            params.cylinder.CopyFrom(shape._to_proto())
         elif isinstance(shape, Torus):
-            params.torus.CopyFrom(shape._to_proto())  # type: ignore
+            params.torus.CopyFrom(shape._to_proto())
         elif isinstance(shape, Cone):
-            params.cone.CopyFrom(shape._to_proto())  # type: ignore
+            params.cone.CopyFrom(shape._to_proto())
         elif isinstance(shape, HalfSphere):
-            params.half_sphere.CopyFrom(shape._to_proto())  # type: ignore
+            params.half_sphere.CopyFrom(shape._to_proto())
         else:
             raise TypeError(f"Unsupported shape type: {type(shape)}")
         self.__create_feature(