luminarycloud 0.13.1__py3-none-any.whl → 0.14.0__py3-none-any.whl

luminarycloud/vis/filters.py

@@ -21,38 +21,32 @@ class Plane:
 
     .. warning:: This feature is experimental and may change or be removed in the future.
 
-    Attributes:
-    -----------
-    origin : Vector3
-        A point defined on the plane. Default: [0,0,0].
-    normal : Vector3
-        The vector orthogonal to the  plane. Default: [0,1,0]
     """
 
     origin: Vector3Like = dc.field(default_factory=lambda: Vector3(x=0, y=0, z=0))
+    """A point defined on the plane. Default: [0,0,0]."""
     normal: Vector3Like = dc.field(default_factory=lambda: Vector3(x=1, y=0, z=0))
+    """The vector orthogonal to the  plane. Default: [0,1,0]"""
 
 
 @dc.dataclass
 class Box:
     """
     This class defines a box used for filter such as box clip.
+
     .. warning:: This feature is experimental and may change or be removed in the future.
 
-    Attributes:
-    -----------
-    center: Vector3
-        A point defined at the center of the box. Default: [0,0,0].
-    lengths: Vector3
-        The the legnths of each side of the box. Default: [1,1,1]
-    angles: Vector3
-        The rotation of the box specified in Euler angles (degrees) and applied
-        in XYZ ordering. Default: [0,0,0]
     """
 
     center: Vector3Like = dc.field(default_factory=lambda: Vector3(x=0, y=0, z=0))
+    """A point defined at the center of the box. Default: [0,0,0]."""
     lengths: Vector3Like = dc.field(default_factory=lambda: Vector3(x=1, y=1, z=1))
+    """The the legnths of each side of the box. Default: [1,1,1]"""
     angles: Vector3Like = dc.field(default_factory=lambda: Vector3(x=0, y=0, z=0))
+    """
+    The rotation of the box specified in Euler angles (degrees) and applied
+    in XYZ ordering. Default: [0,0,0]
+    """
 
 
 class Filter(ABC):
@@ -201,7 +195,7 @@ class Isosurface(Filter):
         if len(self.isovalues) == 0:
             raise ValueError("Isosurface: isovalue must be non-empty")
 
-        if self.field == VisQuantity.NONE:
+        if self.field.quantity == VisQuantity.NONE:
             raise ValueError("Isosurface: field can't be None")
 
         vis_filter = vis_pb2.Filter()
@@ -654,6 +648,8 @@ class SurfaceStreamlines(Streamlines):
         id: str
             A surface id or a tag id.
         """
+        if not isinstance(id, str):
+            raise TypeError(f"Expected 'str', got {type(id).__name__}")
         self._surface_names.append(id)
 
     def _surfaces(self) -> List[str]:
@@ -700,3 +696,88 @@ class SurfaceStreamlines(Streamlines):
             vis_filter.streamlines.surface.surface_names.append(id)
         vis_filter.streamlines.field.quantity_typ = self.field.quantity.value
         return vis_filter
+
+
+class SurfaceLIC(Filter):
+    """
+    A Surface Line Integral Convolution (LIC) filter is used to depict the flow
+    direction and structure of vector fields (such as velocity) on surfaces. It
+    enhances the perception of complex flow patterns by convolving noise
+    textures along streamlines, making it easier to visually interpret the
+    behavior of fluid flow on boundaries or surfaces in a simulation.
+
+    The input is a list of surfaces. If none are specified, all are used. The
+    surface LIC outputs grey scale colors on the specified surfaces. When the
+    display attributes quantity is not None, the field colors are blended with
+    the grey scale colors.
+
+    Note: surface LIC computes on the same surfaces of the solution. If the surfaces in
+    the global display attributes are not hidden, the surface LIC will not be visible since
+    the existing surfaces are occluding it.
+
+    .. warning:: This feature is experimental and may change or be removed in the future.
+
+    Attributes:
+    -----------
+    field: Field
+        Specifies the field used to advect particles for the surface LIC.
+        Default: WALL_SHEER_STRESS
+    contrast: float
+        Contrast controls the contrast of the resuting surface LIC. Valid values
+        are in the [0.2, 3.0] range. Lower values means less contrast and
+        higher values mean more contrast. Default: 1
+    """
+
+    def __init__(self, name: str) -> None:
+        super().__init__(generate_id("surface-lic-"))
+        self.name = name
+        self.contrast: float = 1.0
+        self._surface_names: List[str] = []
+        self.field: Field = Field()
+        self.field.quantity = VisQuantity.WALL_SHEAR_STRESS
+
+    def add_surface(self, id: str) -> None:
+        """
+        Add a surface to generate compute the surface LIC on. Adding no
+        surfaces indicates that all surfaces will be used.
+
+        Parameters
+        ----------
+        id: str
+            A surface id or a tag id.
+        """
+        if not isinstance(id, str):
+            raise TypeError(f"Expected 'str', got {type(id).__name__}")
+        self._surface_names.append(id)
+
+    def _surfaces(self) -> List[str]:
+        """
+        Returns the current list of surfaces.
+        """
+        return self._surface_names
+
+    def _to_proto(self) -> vis_pb2.Filter:
+        vis_filter = vis_pb2.Filter()
+        vis_filter.id = self.id
+        vis_filter.name = self.name
+        # Prevent common mistakes that cause confusion. The only current option
+        # is to be on a surface, so no velocity.
+        if not isinstance(self.field, Field):
+            raise TypeError(f"Expected 'Field', got {type(self.field).__name__}")
+        if self.field.quantity == VisQuantity.VELOCITY:
+            raise ValueError("SurfaceLIC: velocity is 0 on surfaces and will produce no data")
+        if not isinstance(self.contrast, (int, float)):
+            raise TypeError(f"Expected 'int or float', got {type(self.contrast).__name__}")
+        if self.contrast < 0.2 or self.contrast > 3.0:
+            raise ValueError("SurfaceLIC: contrast must be between 0.2 and 3.0")
+
+        for id in self._surface_names:
+            vis_filter.surface_lic.geometry.surface_names.append(id)
+        if len(self._surface_names) == 0:
+            # we need to make sure that the geometry is populated.
+            geometry = vis_pb2.SurfaceLICGeomtery()
+            vis_filter.surface_lic.geometry.CopyFrom(geometry)
+
+        vis_filter.surface_lic.field.quantity_typ = self.field.quantity.value
+        vis_filter.surface_lic.contrast = self.contrast
+        return vis_filter

luminarycloud/vis/interactive_scene.py

@@ -1,7 +1,7 @@
 from .display import DisplayAttributes
 from .filters import SurfaceStreamlines, Filter
 from .._client import get_default_client
-from ..enum.vis_enums import EntityType
+from ..enum.vis_enums import EntityType, SceneMode
 from typing import TYPE_CHECKING, cast
 
 from .._proto.api.v0.luminarycloud.vis import vis_pb2
@@ -25,10 +25,10 @@ class InteractiveScene:
 
     # Using the type causes a circular import error, not sure on best way to resolve.
     # I do want to keep this in a separate file
-    def __init__(self, scene: "Scene") -> None:
+    def __init__(self, scene: "Scene", mode: SceneMode) -> None:
         if not lcj:
             raise ImportError("InteractiveScene requires luminarycloud[jupyter] to be installed")
-        self.widget = lcj.LCVisWidget()
+        self.widget = lcj.LCVisWidget(scene_mode=mode)
         self.set_scene(scene)
 
     def _ipython_display_(self) -> None:

luminarycloud/vis/visualization.py

@@ -39,29 +39,20 @@ class DirectionalCamera:
 
     .. warning:: This feature is experimental and may change or be removed in the future.
 
-    Attributes:
-    -----------
-    name : str
-        A user defined name for the camera.
-    direction : CameraDirection
-        The orientation of the camera. Default: X_POSITIVE
-    projection : CameraProjection
-        The type of projection used for the camera. Default: ORTHOGRAPHIC
-    label: str
-        A user defined label to help distinguish between multiple images.
-        Default: ""
-    width: int
-        The width of the output image in pixels. Default: 1024
-    height: int
-        The height of the output image in pixels. Default: 1024
     """
 
     name: str = "default directional camera"
+    """ A user defined name for the camera. """
     direction: CameraDirection = CameraDirection.X_POSITIVE
+    """ The orientation of the camera. Default: X_POSITIVE """
     projection: CameraProjection = CameraProjection.ORTHOGRAPHIC
+    """ The type of projection used for the camera. Default: ORTHOGRAPHIC """
     label: str = ""
+    """A user defined label to help distinguish between multiple images."""
     width: int = 1024
+    """The width of the output image in pixels. Default: 1024"""
     height: int = 1024
+    """The height of the output image in pixels. Default: 1024"""
 
 
 @dc.dataclass
@@ -73,39 +64,39 @@ class LookAtCamera:
 
     .. warning:: This feature is experimental and may change or be removed in the future.
 
-    Attributes:
-    -----------
-    look_at: Vector3
-        The point the camera is looking at. Default (0,0,0)
-    position: Vector3
-        The position of the camera. Default (0,1,0)
-    up: Vector3
-        The up vector for the camera. Default (0,0,1)
-    projection : CameraProjection
-        The type of projection used for the camera. Default: ORTHOGRAPHIC
-    label: str
-        A user defined label to help distinguish between multiple images. Default: ""
-    width: int
-        The width of the output image in pixels. Default: 1024
-    height: int
-        The height of the output image in pixels. Default: 1024
     """
 
     look_at: Vector3Like = dc.field(default_factory=lambda: Vector3(x=0, y=0, z=0))
+    """ The point the camera is looking at. Default (0,0,0) """
     position: Vector3Like = dc.field(default_factory=lambda: Vector3(x=0, y=1, z=0))
+    """ The position of the camera. Default (0,1,0) """
     up: Vector3Like = dc.field(default_factory=lambda: Vector3(x=0, y=0, z=1))
+    """ The up vector for the camera. Default (0,0,1) """
     projection: CameraProjection = CameraProjection.ORTHOGRAPHIC
+    """ The type of projection used for the camera. Default: ORTHOGRAPHIC """
     label: str = ""
+    """ A user defined label to help distinguish between multiple images. Default: "" """
     width: int = 1024
+    """ The width of the output image in pixels. Default: 1024 """
     height: int = 1024
+    """ The height of the output image in pixels. Default: 1024 """
+
+
+class _InternalToken:
+    """Marker class to control instantiation access for RenderOutput."""
+
+    pass
 
 
 class RenderOutput:
     """
-    The render output represents the request to render images from a geometry, mesh or
-    solution. The operation exectutes asyncronously, so the caller must check
-    the status of the image extract. If the status is completed, then the
-    resuling image is available for download.
+    The render output represents the request to render images from a geometry,
+    mesh or solution, and is contructed by the Scene class. The operation
+    exectutes asyncronously, so the caller must check the status of the image
+    extract. If the status is completed, then the resuling image is available
+    for download.
+
+    .. warning:: This class should not be directly instantiated by users.
 
     .. warning:: This feature is experimental and may change or be removed in the future.
 
@@ -125,17 +116,27 @@ class RenderOutput:
         Internal flag to track if the extract has been deleted.
     """
 
-    def __init__(
-        self, extract_id: str, project_id: str, name: str, desciption: str, status: RenderStatusType
-    ):
+    def __init__(self, factory_token: _InternalToken):
+        if not isinstance(factory_token, _InternalToken):
+            raise ValueError("This class can only be constructed through the Scene class")
+
         # TODO(matt): We could make all of these read only.
-        self._extract_id: str = extract_id
-        self._project_id: str = project_id
-        self.status: RenderStatusType = status
-        self.name: str = name
-        self.description: str = desciption
+        self._extract_id: str = ""
+        self._project_id: str = ""
+        self.status: RenderStatusType = RenderStatusType.INVALID
+        self.name: str = ""
+        self.description: str = ""
         self._deleted = False
 
+    def _set_data(
+        self, extract_id: str, project_id: str, name: str, desciption: str, status: RenderStatusType
+    ) -> None:
+        self._extract_id = extract_id
+        self._project_id = project_id
+        self.status = status
+        self.name = name
+        self.description = desciption
+
     def __repr__(self) -> str:
         return f"RenderOutput(Id: {self._extract_id} status: {self.status})"
 
@@ -311,6 +312,10 @@ class Scene:
         annotations for all fields used in global and filter display attributes.
         When False, only color maps explicitly added by the user appear in the
         images. Default: True
+    supersampling: int
+        Supersampling controls anti-aliasing in output images. A value of 1 means no supersampling.
+        A value of 2 means we internally render at 2x the image resolution and downsample the image
+        to the requested resolution. Valid values are between 1 and 8. Default: 2
     """
 
     def __init__(self, entity: Geometry | Mesh | Solution):
@@ -318,6 +323,7 @@ class Scene:
         self.axes_grid_visible: bool = True
         self.background_color: Vector3 = Vector3(x=0, y=0, z=0)
         self.auto_color_map_annotations = True
+        self.supersampling: int = 2
         # Global display attrs
         self.global_display_attrs = DisplayAttributes()
         self._filters: List[Filter] = []
@@ -621,8 +627,9 @@ class Scene:
                 # These are all default contructed, so they all have the same dimentions.
                 # All the coordinates are in normalized device space.
                 assert auto_cmaps[0].appearance != None
-                width = auto_cmaps[0].appearance.width
-                height = auto_cmaps[0].appearance.height
+                appearance = cast(ColorMapAppearance, auto_cmaps[0].appearance)
+                width = appearance.width
+                height = appearance.height
                 x_padding = 0.05
                 y_padding = 0.05
                 # Placing them on the right side.
@@ -630,8 +637,9 @@ class Scene:
                 lower_left_y = 1.0 - height - y_padding
                 for cmap in auto_cmaps:
                     assert cmap.appearance != None
-                    cmap.appearance.lower_left_x = lower_left_x
-                    cmap.appearance.lower_left_y = lower_left_y
+                    cmap_appearance = cast(ColorMapAppearance, cmap.appearance)
+                    cmap_appearance.lower_left_x = lower_left_x
+                    cmap_appearance.lower_left_y = lower_left_y
                     lower_left_y = lower_left_y - height - y_padding
                     if lower_left_y < 0:
                         lower_left_y = 0
@@ -654,6 +662,12 @@ class Scene:
         req.spec.background_properties.color.b = bg_color.z
         req.spec.background_properties.color.a = 1
 
+        if not isinstance(self.supersampling, int):
+            raise TypeError(f"Expected 'int', got {type(self.supersampling).__name__}")
+        if self.supersampling < 1 or self.supersampling > 8:
+            raise ValueError(f"Supersampling value is not in the range [1,8]: {self.supersampling}")
+        req.spec.supersampling_ratio = self.supersampling
+
         req.project_id = self._project_id
         if self._entity_type == EntityType.SIMULATION:
             req.spec.entity_type.simulation.id = self._solution.simulation_id
@@ -682,22 +696,24 @@ class Scene:
         req: vis_pb2.CreateExtractRequest = self._create_request(name=name, description=description)
         res: vis_pb2.CreateExtractResponse = get_default_client().CreateExtract(req)
         logger.info("Successfully submitted 'render_images' request")
-        return RenderOutput(
+        render_output = RenderOutput(_InternalToken())
+        render_output._set_data(
             extract_id=res.extract.extract_id,
             project_id=self._project_id,
             name=name,
             desciption=description,
             status=RenderStatusType(res.extract.status),
         )
+        return render_output
 
-    def interact(self) -> InteractiveScene:
+    def interact(self, scene_mode: SceneMode = SceneMode.SIDE_PANEL) -> InteractiveScene:
         """
         Start an interactive display of the scene, when running inside LuminaryCloud's
         AI Notebook environment or Jupyter Lab. The returned object must be displayed
         in the notebook to display the interactive visualization. This requires that
         the luminarycloud package was installed with the optional jupyter feature.
         """
-        self._interactive_scene = InteractiveScene(self)
+        self._interactive_scene = InteractiveScene(self, mode=scene_mode)
         return self._interactive_scene
 
 
@@ -719,14 +735,15 @@ def get_render(project_id: str, extract_id: str) -> RenderOutput:
     req.extract_id = extract_id
     req.project_id = project_id
     res: vis_pb2.GetExtractResponse = get_default_client().GetExtract(req)
-    output = RenderOutput(
+    render_output = RenderOutput(_InternalToken())
+    render_output._set_data(
         extract_id=extract_id,
         project_id=project_id,
         name=res.extract.name,
         desciption=res.extract.description,
         status=RenderStatusType(res.extract.status),
     )
-    return output
+    return render_output
 
 
 def list_quantities(solution: Solution) -> List[VisQuantity]:
@@ -807,15 +824,14 @@ def list_renders(entity: Geometry | Mesh | Solution) -> List[RenderOutput]:
 
     results: List[RenderOutput] = []
     for extract in res.extracts:
-        result = RenderOutput(
+        result = RenderOutput(_InternalToken())
+        result._set_data(
             extract_id=extract.extract_id,
             project_id=extract.project_id,
             name=extract.name,
             desciption=extract.description,
             status=RenderStatusType(extract.status),
         )
-
-        # TODO(matt): the List extracts request is giving us nil for the status.
         # This need to be fixed on the backend, but manually refreshing works for now.
         result.refresh()
         results.append(result)

{luminarycloud-0.13.1.dist-info → luminarycloud-0.14.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: luminarycloud
-Version: 0.13.1
+Version: 0.14.0
 Summary: Luminary Cloud SDK
 Project-URL: Homepage, https://www.luminarycloud.com/
 Project-URL: Documentation, https://app.luminarycloud.com/docs/api/