ansys-speos-core 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

ansys/speos/core/generic/constants.py

@@ -0,0 +1,36 @@
+# Copyright (C) 2021 - 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""Collection of all constants used in pySpeos."""
+
+import os
+
+DEFAULT_HOST = "localhost"
+"""Default host used by Speos RPC server and client """
+DEFAULT_PORT = "50098"
+"""Default port used by Speos RPC server and client """
+DEFAULT_VERSION = "251"
+"""Latest supported Speos version of the current PySpeos Package"""
+MAX_MESSAGE_LENGTH = int(os.environ.get("SPEOS_MAX_MESSAGE_LENGTH", 256 * 1024**2))
+"""Maximum message length value accepted by the Speos RPC server,
+By default, value stored in environment variable SPEOS_MAX_MESSAGE_LENGTH or 268 435 456.
+"""

ansys/speos/core/generic/general_methods.py

@@ -25,9 +25,24 @@
 this includes decorator and methods
 """
 
-from functools import wraps
+from functools import lru_cache, wraps
+import os
+from pathlib import Path
+from typing import List, Optional, Union
 import warnings
 
+import numpy as np
+
+from ansys.speos.core.generic.constants import DEFAULT_VERSION
+from ansys.tools.path import get_available_ansys_installations
+
+_GRAPHICS_AVAILABLE = None
+
+GRAPHICS_ERROR = (
+    "Preview unsupported without 'ansys-tools-visualization_interface' installed. "
+    "You can install this using `pip install ansys-speos-core[graphics]`."
+)
+
 
 def deprecate_kwargs(old_arguments: dict, removed_version="0.3.0"):
     """Issues deprecation warnings for arguments.
@@ -62,3 +77,153 @@ def deprecate_kwargs(old_arguments: dict, removed_version="0.3.0"):
         return wrapper
 
     return decorator
+
+
+@lru_cache
+def run_if_graphics_required(warning=False):
+    """Check if graphics are available."""
+    global _GRAPHICS_AVAILABLE
+    if _GRAPHICS_AVAILABLE is None:
+        try:
+            import pyvista as pv  # noqa: F401
+
+            from ansys.tools.visualization_interface import Plotter  # noqa: F401
+
+            _GRAPHICS_AVAILABLE = True
+        except ImportError:  # pragma: no cover
+            _GRAPHICS_AVAILABLE = False
+
+    if _GRAPHICS_AVAILABLE is False and warning is False:  # pragma: no cover
+        raise ImportError(GRAPHICS_ERROR)
+    elif _GRAPHICS_AVAILABLE is False:  # pragma: no cover
+        warnings.warn(GRAPHICS_ERROR)
+
+
+def graphics_required(method):
+    """Decorate a method as requiring graphics.
+
+    Parameters
+    ----------
+    method : callable
+        Method to decorate.
+
+    Returns
+    -------
+    callable
+        Decorated method.
+    """
+
+    def wrapper(*args, **kwargs):
+        run_if_graphics_required()
+        return method(*args, **kwargs)
+
+    return wrapper
+
+
+def magnitude_vector(vector: Union[List[float], np.array]) -> float:
+    """
+    Compute the magnitude (length) of a 2D or 3D vector using NumPy.
+
+    Parameters
+    ----------
+    vector: List[float]
+        A 2D or 3D vector as a list [x, y] or [x, y, z].
+
+    Returns
+    -------
+    float
+        The magnitude (length) of the vector.
+    """
+    vector_np = np.array(vector, dtype=float)
+    if vector_np.size not in (2, 3):
+        raise ValueError("Input vector must be either 2D or 3D")
+    return np.linalg.norm(vector_np)
+
+
+def normalize_vector(vector: Union[List[float], np.array]) -> List[float]:
+    """
+    Normalize a 2D or 3D vector to have a length of 1 using NumPy.
+
+    Parameters
+    ----------
+    vector: List[float]
+        A vector as a list [x, y] for 2D or [x, y, z] for 3D.
+
+    Returns
+    -------
+    List[float]
+        The normalized vector.
+    """
+    vector_np = np.array(vector, dtype=float)
+    if vector_np.size not in (2, 3):
+        raise ValueError("Input vector must be either 2D or 3D")
+
+    magnitude = magnitude_vector(vector_np)
+    if magnitude == 0:
+        raise ValueError("Cannot normalize the zero vector")
+
+    return (vector_np / magnitude).tolist()
+
+
+def error_no_install(install_path: Union[Path, str], version: Union[int, str]):
+    """Raise error that installation was not found at a location.
+
+    Parameters
+    ----------
+    install_path : Union[Path, str]
+        Installation Path
+    version : Union[int, str]
+        Version
+    """
+    install_loc_msg = ""
+    if install_path:
+        install_loc_msg = f"at {Path(install_path).parent}"
+    raise FileNotFoundError(
+        f"Ansys Speos RPC server installation not found{install_loc_msg}. "
+        f"Please define AWP_ROOT{version} environment variable"
+    )
+
+
+def retrieve_speos_install_dir(
+    speos_rpc_path: Optional[Union[Path, str]] = None, version: str = DEFAULT_VERSION
+) -> Path:
+    """Retrieve Speos install location based on Path or Environment.
+
+    Parameters
+    ----------
+    speos_rpc_path : Optional[str, Path]
+        location of Speos rpc executable
+    version : Union[str, int]
+        The Speos server version to run, in the 3 digits format, such as "242".
+        If unspecified, the version will be chosen as
+        ``ansys.speos.core.kernel.client.LATEST_VERSION``.
+
+    """
+    if not speos_rpc_path:
+        speos_rpc_path = ""
+    if not speos_rpc_path or not Path(speos_rpc_path).exists():
+        if not Path(speos_rpc_path).exists():
+            warnings.warn(
+                "Provided executable location not found, looking for local installation",
+                UserWarning,
+            )
+        versions = get_available_ansys_installations()
+        ansys_loc = versions.get(int(version), False)
+        if not ansys_loc:
+            ansys_loc = os.environ.get("AWP_ROOT{}".format(version), False)
+            if not ansys_loc:
+                error_no_install(speos_rpc_path, int(version))
+
+        speos_rpc_path = Path(ansys_loc) / "Optical Products" / "SPEOS_RPC"
+    elif Path(speos_rpc_path).is_file():
+        if "SpeosRPC_Server" not in Path(speos_rpc_path).name:
+            error_no_install(speos_rpc_path, int(version))
+        else:
+            speos_rpc_path = Path(speos_rpc_path).parent
+    if os.name == "nt":
+        speos_exec = speos_rpc_path / "SpeosRPC_Server.exe"
+    else:
+        speos_exec = speos_rpc_path / "SpeosRPC_Server.x"
+    if not speos_exec.is_file():
+        error_no_install(speos_rpc_path, int(version))
+    return speos_rpc_path

ansys/speos/core/generic/visualization_methods.py

@@ -0,0 +1,289 @@
+# Copyright (C) 2021 - 2025 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+"""Provides the ``VisualData`` class."""
+
+from typing import TYPE_CHECKING, List
+
+from ansys.speos.core.generic.general_methods import (
+    graphics_required,
+    magnitude_vector,
+    normalize_vector,
+)
+
+if TYPE_CHECKING:  # pragma: no cover
+    import pyvista as pv
+
+
+@graphics_required
+class _VisualCoordinateSystem:
+    """Visualization data for the coordinate system..
+
+    By default, there is empty visualization data.
+
+    Notes
+    -----
+    **Do not instantiate this class yourself**.
+    """
+
+    def __init__(self):
+        import pyvista as pv
+
+        self.__origin = [0.0, 0.0, 0.0]
+        self.__x_axis = pv.Arrow(
+            start=self.__origin,
+            direction=[1.0, 0.0, 0.0],
+            scale=10.0,
+            tip_radius=0.05,
+            shaft_radius=0.01,
+        )
+        self.__y_axis = pv.Arrow(
+            start=self.__origin,
+            direction=[0.0, 1.0, 0.0],
+            scale=10.0,
+            tip_radius=0.05,
+            shaft_radius=0.01,
+        )
+        self.__z_axis = pv.Arrow(
+            start=self.__origin,
+            direction=[0.0, 0.0, 1.0],
+            scale=10.0,
+            tip_radius=0.05,
+            shaft_radius=0.01,
+        )
+
+    @property
+    def origin(self) -> List[float]:
+        """Returns the origin of the coordinate system.
+
+        Returns
+        -------
+        List[float]
+            The origin of the coordinate system.
+
+        """
+        return self.__origin
+
+    @origin.setter
+    def origin(self, value: List[float]) -> None:
+        """Set the origin of the coordinate system.
+
+        Parameters
+        ----------
+        value: List[float]
+            The origin of the coordinate system.
+
+        Returns
+        -------
+        None
+        """
+        if len(value) != 3:
+            raise ValueError("origin must be a List of three values.")
+        self.__origin = value
+
+    @property
+    def x_axis(self) -> "pv.Arrow":
+        """Returns the x-axis of the coordinate system.
+
+        Returns
+        -------
+        pv.Arrow
+            pyvista.Arrow the x-axis of the coordinate system.
+
+        """
+        return self.__x_axis
+
+    @x_axis.setter
+    def x_axis(self, x_vector: List[float]) -> None:
+        """Set the x-axis of the coordinate system.
+
+        Parameters
+        ----------
+        x_vector: List[float]
+            The x-axis of the coordinate system.
+
+        Returns
+        -------
+        None
+        """
+        import pyvista as pv
+
+        if len(x_vector) != 3:
+            raise ValueError("x_axis must be a List of three values.")
+        self.__x_axis = pv.Arrow(
+            start=self.__origin,
+            direction=normalize_vector(vector=x_vector),
+            scale=magnitude_vector(vector=x_vector),
+            tip_radius=0.05,
+            shaft_radius=0.01,
+        )
+
+    @property
+    def y_axis(self) -> "pv.Arrow":
+        """
+        Returns the y-axis of the coordinate system.
+
+        Returns
+        -------
+        pv.Arrow
+            pyvista.Arrow the y-axis of the coordinate system.
+
+        """
+        return self.__y_axis
+
+    @y_axis.setter
+    def y_axis(self, y_vector: List[float]) -> None:
+        """Set the y-axis of the coordinate system.
+
+        Parameters
+        ----------
+        y_vector: List[float]
+            The y-axis of the coordinate system.
+
+        Returns
+        -------
+        None
+        """
+        import pyvista as pv
+
+        if len(y_vector) != 3:
+            raise ValueError("y_axis must be a List of three values.")
+        self.__y_axis = pv.Arrow(
+            start=self.__origin,
+            direction=normalize_vector(vector=y_vector),
+            scale=magnitude_vector(vector=y_vector),
+            tip_radius=0.05,
+            shaft_radius=0.01,
+        )
+
+    @property
+    def z_axis(self) -> "pv.Arrow":
+        """
+        Returns the z-axis of the coordinate system.
+
+        Returns
+        -------
+        pv.Arrow
+            pyvista.Arrow the z-axis of the coordinate system.
+
+        """
+        return self.__z_axis
+
+    @z_axis.setter
+    def z_axis(self, z_vector: List[float]) -> None:
+        """Set the z-axis of the coordinate system.
+
+        Parameters
+        ----------
+        z_vector: List[float]
+            The z-axis of the coordinate system.
+
+        Returns
+        -------
+        None
+        """
+        import pyvista as pv
+
+        if len(z_vector) != 3:
+            raise ValueError("z_axis must be a List of three values.")
+        self.__z_axis = pv.Arrow(
+            start=self.__origin,
+            direction=normalize_vector(vector=z_vector),
+            scale=magnitude_vector(vector=z_vector),
+            tip_radius=0.05,
+            shaft_radius=0.01,
+        )
+
+
+@graphics_required
+class _VisualData:
+    """Visualization data for the sensor.
+
+    By default, there is empty visualization data.
+
+    Notes
+    -----
+    **Do not instantiate this class yourself**
+    """
+
+    def __init__(self, coordinate_system=True):
+        import pyvista as pv
+
+        self.__data = pv.PolyData()
+        self.coordinates = _VisualCoordinateSystem() if coordinate_system else None
+        self.updated = False
+
+    @property
+    def data(self) -> "pv.PolyData":
+        """
+        Returns the data of the sensor.
+
+        Returns
+        -------
+        pv.PolyData
+            The data of the surface visualization.
+
+        """
+        return self.__data
+
+    def add_data_triangle(self, triangle_vertices: List[List[float]]) -> None:
+        """
+        Add surface data triangle to Visualization data.
+
+        Parameters
+        ----------
+        triangle_vertices: List[List[float]]
+            The vertices of the triangle.
+
+        Returns
+        -------
+        None
+        """
+        import pyvista as pv
+
+        if len(triangle_vertices) != 3 or any(len(vertex) != 3 for vertex in triangle_vertices):
+            raise ValueError(
+                "triangle_vertices is expected to be composed of 3 vertices with 3 elements each."
+            )
+        faces = [[3, 0, 1, 2]]
+        self.__data = self.__data.append_polydata(pv.PolyData(triangle_vertices, faces))
+
+    def add_data_rectangle(self, rectangle_vertices: List[List[float]]) -> None:
+        """
+        Add surface data rectangle to Visualization data.
+
+        Parameters
+        ----------
+        rectangle_vertices: List[List[float]]
+            The vertices of the rectangle.
+
+        Returns
+        -------
+        None
+        """
+        import pyvista as pv
+
+        if len(rectangle_vertices) != 3 or any(len(vertex) != 3 for vertex in rectangle_vertices):
+            raise ValueError(
+                "rectangle_vertices is expected to be composed of 3 vertices with 3 elements each."
+            )
+        self.__data = self.__data.append_polydata(pv.Rectangle(rectangle_vertices))