RS3Scripting 4.42.0__py3-none-any.whl

rs3/ApplicationManager.py

@@ -0,0 +1,77 @@
+import subprocess
+import time
+from multiprocessing.connection import Listener
+from logging import Logger
+
+class ApplicationManager:
+    minimumPort = 49152
+    maximumPort = 65535
+    defaultTimeout = 120
+    def startApplication(self, pathToExecutable : str, port : int, isServerRunning : callable, logger : Logger, timeout : float = defaultTimeout ):
+        """
+        Starts the application specified by pathToExecutable and starts the python server on the given port. 
+        Returns when the server is ready to accept requests.
+        Throws TimeoutError exception if the server is not ready within that time.
+
+        Args:
+            pathToExecutable: the full path to the executable of the application you want to start.
+            port: the port number you want the python server to bind to.
+            isServerRunning: a callable that returns True if the server is ready to accept requests.
+            logger: a logger object. It will be disabled while trying to connect to the server.
+            timeout: time in seconds before we stop trying to start the application
+        
+        Raises:
+        	ValueError: Port range must be between 49152 and 65535, otherwise ValueError is raised
+		    TimeoutError: if timeout is provided, raises TimeoutError if not able to connect to the server within that time.
+        """
+        if port < self.minimumPort or port > self.maximumPort:
+            msg = f"port must be in the range {self.minimumPort} to {self.maximumPort}"
+            logger.error(msg)
+            raise ValueError(msg)
+        
+        if not self._isPortAvailable(port):
+            msg = f"port number {port} is occupied. Please choose another port."
+            logger.error(msg)
+            raise RuntimeError(msg)
+
+        logger.info(f"Attempting to start the application at {pathToExecutable} and binding server to port {port}...")
+        subprocess.Popen([f"{pathToExecutable}", "-startScriptingServer", f"{port}"], start_new_session = True, creationflags=subprocess.DETACHED_PROCESS)
+
+        self._tryToConnectToServer(port, isServerRunning, timeout, logger)
+       
+
+    def _isPortAvailable(self, port):
+        portAvailable = False
+        listener = None
+        try:
+            listener = Listener(('localhost', port), 'AF_INET')
+            portAvailable = True
+        except Exception:
+            portAvailable = False
+        
+        if listener:
+            listener.close()
+
+        return portAvailable
+
+    def _tryToConnectToServer(self, port : int, isServerRunning : callable, timeout, logger : Logger):
+
+        startTime = time.time()
+        serverIsRunning = False
+
+        while not serverIsRunning:
+            if timeout:
+                if (time.time() - startTime) > timeout:
+                    msg = "The application did not start within the given timeout time."
+                    logger.error(msg)
+                    raise TimeoutError(msg)
+            try:
+                logger.debug("Trying to connect to the server...")
+                logger.disabled = True
+                isServerRunning(port)
+            except Exception as e:
+                continue
+            finally:
+                logger.disabled = False
+            serverIsRunning = True
+            logger.debug("connectied!")

rs3/ColorPicker.py

@@ -0,0 +1,123 @@
+from enum import Enum
+
+class ColorType(Enum):
+    Black = 0x000000
+    Brown = 0x002AA5
+    Dark_Olive_Green = 0x404000
+    Dark_Green = 0x005500
+    Dark_Teal = 0x5E0000
+    Dark_Blue = 0x8B0000
+    Indigo = 0x82004B
+    Dark_Grey = 0x282828
+
+    Dark_Red = 0x00008B
+    Orange = 0x2068FF
+    Dark_Yellow = 0x008B8B
+    Green = 0x009300
+    Teal = 0x8E8E38
+    Blue = 0xFF0000
+    Blue_Grey = 0xC07B7B
+    Grey_40 = 0x666666
+
+    Red = 0x0000FF
+    Light_Orange = 0x5BADFF
+    Lime = 0x32CD32
+    Sea_Green = 0x71B33C
+    Aqua = 0xD4FF7F
+    Light_Blue = 0xC09E7D
+    Violet = 0x800080
+    Grey_50 = 0x7F7F7F
+
+    Pink = 0xCBC0FF
+    Gold = 0x00D7FF
+    Yellow = 0x00FFFF
+    Bright_Green = 0x00FF00
+    Turquoise = 0xD0E040
+    Skyblue = 0xFFFFC0
+    Plum = 0x480048
+    Light_Grey = 0xC0C0C0
+
+    Rose = 0xE1E4FF
+    Tan = 0x8CB4D2
+    Light_Yellow = 0xE0FFFF
+    Pale_Green = 0x98FB98
+    Pale_Turquoise = 0xEEEEAF
+    Pale_Blue = 0x8B8368
+    Lavender = 0xFAE6E6
+    White = 0xFFFFFF
+    
+class ColorPicker():
+    def getRGBFromColor(color: int):
+        """
+        Returns the RGB representation of a color from its int value
+
+        Parameters:
+            color (int) : int representing the color
+
+        Returns: 
+            tuple containing red, green and blue values of the color. Each of red, green and blue are between 0 and 255 inclusive
+                    
+        """
+        # Internally MSFT COLORREF stores the byte ordering of RGB Color as BGR: 0x00bbggrr
+        blue = (color >> 16) & 0xFF
+        green = (color >> 8) & 0xFF
+        red = color & 0xFF
+
+        return (red, green, blue)
+    
+    def getColorFromRGB(red: int, green: int, blue: int):
+        """
+        Returns the int representation of a color from its R, G, B values
+        
+        Parameters:
+                red (int) : int representing red value of the color. Must be between 0 and 255 inclusive
+                green (int) : int representing green value of the color. Must be between 0 and 255 inclusive
+                blue (int) : int representing blue value of the color. Must be between 0 and 255 inclusive
+
+            Returns: int representation of color formed combining rgb values
+        """
+        if not (0 <= red <= 255 and 0 <= green <= 255 and 0 <= blue <= 255):
+                raise ValueError("Red, Green, and Blue values must be between 0 and 255, inclusive")
+        
+        # Internally MSFT COLORREF stores the byte ordering of RGB Color as BGR: 0x00bbggrr
+        return (blue << 16) | (green << 8) | red
+    
+    def _setColorValidation(*args):
+        if len(args) == 1:
+            color_input = args[0]
+
+            if isinstance(color_input, str):
+                # Hex string case
+                hex_color = color_input.lstrip('#')
+                if len(hex_color) not in (6, 8):
+                    raise ValueError("Hex string must be 6 or 8 characters long.")
+                red = int(hex_color[0:2], 16)
+                green = int(hex_color[2:4], 16)
+                blue = int(hex_color[4:6], 16)
+                alpha = int(hex_color[6:8], 16) if len(hex_color) == 8 else 255
+
+            elif isinstance(color_input, ColorType):
+                red, green, blue = ColorPicker.getRGBFromColor(color_input.value)
+                alpha = 255
+
+            elif isinstance(color_input, int):
+                red, green, blue = ColorPicker.getRGBFromColor(color_input)
+                alpha = 255
+
+            else:
+                raise ValueError("Unsupported single-argument input type.")
+
+        elif 3 <= len(args) <= 4 and all(isinstance(a, int) for a in args):
+            red, green, blue = args[0], args[1], args[2]
+            alpha = args[3] if len(args) == 4 else 255
+
+        else:
+            raise ValueError("Invalid arguments. Provide RGB[A] ints, hex string, ColorType, or int.")
+
+        # Validate
+        for value, name in zip((red, green, blue, alpha), ['R', 'G', 'B', 'A']):
+            if not (0 <= value <= 255):
+                raise ValueError(f"{name} value must be between 0 and 255.")
+            
+        color_bytes = bytes([red, green, blue, alpha])
+        return color_bytes

rs3/CommonEnums.py

@@ -0,0 +1,16 @@
+from enum import Enum
+    
+class LinearDirectionType(Enum):
+    TREND_PLUNGE = "LINEAR_DIRECTION_TREND_PLUNGE"
+    NORMAL_VECTOR = "LINEAR_DIRECTION_VECTOR"
+
+class AutoRestraintsType(Enum):
+    # NONE = 0
+    UNDERGROUND = 1
+    SURFACE_PINS = 2
+    SURFACE_ROLLERS = 3
+    
+class ExternalVolumeRoles(Enum):
+    GEOLOGY = "Geology"
+    CONSTRUCTION = "Construction"
+    EXCAVATION = "Excavation"

rs3/Compute.py

@@ -0,0 +1,105 @@
+from rs3._client import Client
+import rs3.generatedFiles.ComputeService_pb2 as ComputeService
+import rs3.generatedFiles.ComputeService_pb2_grpc as ComputeServiceGrpc
+from rs3._proxyObject import _ProxyObject
+from rs3.ModelEnums import *
+
+class StageSRFValueConvergenceStatus:
+    def __init__(self, isRecovery: bool, stagesConvergence: list[ComputeService.convergenceStatus], srfValuesConvergence: list[ComputeService.convergenceStatus]):
+        self._isRecovery = isRecovery
+        # Convert IndexConvergenceStatusPair objects to tuples
+        self._stagesConvergence = [(pair.index, pair.converged) for pair in stagesConvergence]
+        self._srfValuesConvergence = [(pair.index, pair.converged) for pair in srfValuesConvergence]
+
+    @property
+    def IsRecovery(self):
+        return self._isRecovery
+    
+    @property
+    def StagesConvergence(self):
+        return self._stagesConvergence
+    
+    @property
+    def SrfValuesConvergence(self):
+        return self._srfValuesConvergence
+
+    @property
+    def Printable(self):
+        return self._srfValuesConvergencePrintable() or self._stagesConvergencePrintable()
+
+    def _stagesConvergencePrintable(self):
+        return len(self._stagesConvergence) > 0
+
+    def _printStagesConvergence(self):
+        if not self._stagesConvergencePrintable():
+            return
+        print("Stages Convergence:")
+        print(f"{'Stage':<8} {'Status':<8}")
+        print("-" * 16)
+        for stage, converged in self._stagesConvergence:
+            status = "Yes" if converged else "No"
+            print(f"{stage:<8} {status:<8}")
+
+    def _srfValuesConvergencePrintable(self):
+        return len(self._srfValuesConvergence) > 0
+
+    def _printSrfValuesConvergence(self):
+        if not self._srfValuesConvergencePrintable():
+            return
+        print("SRF Values Convergence:")
+        print(f"{'SRF Value':<8} {'Status':<8}")
+        print("-" * 16)
+        for srfValue, converged in self._srfValuesConvergence:
+            status = "Yes" if converged else "No"
+            print(f"{srfValue:<8} {status:<8}")
+
+    def Print(self):
+        if not self.Printable:
+            return
+        print(f"Recovery: {self._isRecovery}")
+        self._printStagesConvergence()
+        self._printSrfValuesConvergence()
+
+class Compute(_ProxyObject):
+    """
+    Example:
+        See :ref:`compute_example`.
+    """
+    def __init__(self, client: Client, projectId: str):
+        super().__init__(client, projectId)
+        self._computeService = ComputeServiceGrpc.ComputeServiceStub(self._client.channel)
+
+    def compute(self, computeType : ComputeType = ComputeType.ALL, computeStart : ComputeStart = ComputeStart.AFTER_LAST_COMPUTED_STAGE) -> tuple[bool, str]:
+        """
+        Compute stress results (automatically compute groundwater too, if required). Mesh is required before compute.
+        """
+        request = ComputeService.computeRequest(_projectId=self._objectId, computeType=computeType.value, computeStart=computeStart.value)
+        response = self._client.callFunction(self._computeService.compute, request)
+        success = response.result == ""
+        if success:
+            self.printConvergenceStatus()
+     
+        return success, response.result
+    
+    def computeGroundWater(self) -> tuple[bool, str]:
+        """
+        Compute groundwater only (stress analysis will not be computed). Mesh is required before compute.
+        """
+        return self.compute(computeType=ComputeType.GROUNDWATER_ONLY, computeStart=ComputeStart.AFTER_LAST_COMPUTED_STAGE)    
+
+    def printConvergenceStatus(self):
+        success, errorMessage, convergenceStatus = self.readConvergenceStatus()
+        if success and convergenceStatus.Printable:
+            convergenceStatus.Print()
+        elif not success:
+            print(f"Error: {errorMessage}")
+
+    def readConvergenceStatus(self) -> tuple[bool, str, StageSRFValueConvergenceStatus]:
+        """
+        This function returns the availability of convergence status, error message if there is any, and convergence status. To check
+        the convergence of each stage, users may check StagesConvergence and SrfValuesConvergence of StageSRFValueConvergenceStatus.
+        """
+        request = ComputeService.readStagesSSRConvergenceStatusRequest(_projectId=self._objectId)
+        response = self._client.callFunction(self._computeService.readStagesSRFValuesConvergence, request)
+        convergenceStatus = StageSRFValueConvergenceStatus(response.isRecovery, response.stagesConvergence, response.srfValuesConvergence)
+        return response.success, response.errorMessage, convergenceStatus

rs3/ExternalVolume.py

@@ -0,0 +1,48 @@
+import rs3.generatedFiles.ExternalVolumesService_pb2_grpc as ExternalVolumesService_pb2_grpc
+import rs3.generatedFiles.ExternalVolumesService_pb2 as ExternalVolumesService_pb2
+import rs3.generatedFiles.CommonMessages_pb2 as CommonMessages_pb2
+from rs3.CommonEnums import *
+from rs3.properties._PropertyAccessor import PropertyAccessor
+from rs3._proxyObject import _ProxyObject
+from rs3._client import Client
+
+class ExternalVolume(_ProxyObject):
+    """
+	Examples:
+        See :ref:`external_volume_and_selection_example`.		
+	"""
+    def __init__(self, client : Client, projectID : str):
+        super().__init__(client, projectID)
+        self._externalVolumesService = ExternalVolumesService_pb2_grpc.ExternalVolumesServiceStub(self._client.channel)
+        self._propertyAccessor = PropertyAccessor(client, projectID, self._externalVolumesService)
+        
+    def setName(self, name : str):    
+        request = CommonMessages_pb2.SetPropertyRequest(objectId=self._objectId, propertyName="Name", value=CommonMessages_pb2.PropertyValue(stringValue=name))
+        self._client.callFunction(self._externalVolumesService.SetExternalVolumeName, request)
+    def getName(self) -> str:
+        return self._propertyAccessor.getStringValue("Name")
+    
+    def setRole(self, role : ExternalVolumeRoles):
+        request = CommonMessages_pb2.SetPropertyRequest(objectId=self._objectId, propertyName="Role", value=CommonMessages_pb2.PropertyValue(stringValue=role.value))
+        self._client.callFunction(self._externalVolumesService.SetExternalVolumeRole, request)
+    def getRole(self) -> ExternalVolumeRoles:
+        return ExternalVolumeRoles(self._propertyAccessor.getStringValue("Role"))
+    
+    def setAppliedMaterialProperty(self, stageNum : int, materialName : str):
+        """
+        Assign material to the given stage by material name. If the external volume is excavated, "No Material" should be used as the materialName.
+        """
+        request = ExternalVolumesService_pb2.SetAppliedMaterialPropertyRequest(objectId=self._objectId, stageNum=stageNum, materialName=materialName)
+        self._client.callFunction(self._externalVolumesService.SetAppliedMaterialProperty, request)
+    def getAppliedMaterialProperty(self, stageNum : int):
+        request = ExternalVolumesService_pb2.GetAppliedMaterialPropertyRequest(objectId=self._objectId, stageNum=stageNum)
+        response : ExternalVolumesService_pb2.GetAppliedMaterialPropertyResponse = self._client.callFunction(self._externalVolumesService.GetAppliedMaterialProperty, request)
+        return response.materialName
+    
+    def getVolume(self) -> str:
+        return self._propertyAccessor.getDoubleProperty("Volume")
+    
+    def getTotalSurfaceArea(self) -> str:
+        return self._propertyAccessor.getDoubleProperty("Area")
+    
+    

rs3/Geometry.py

@@ -0,0 +1,74 @@
+from dataclasses import dataclass
+import rs3.generatedFiles.CommonGeometryMessages_pb2 as CommonGeometryMessages
+
+class Geometry:
+    pass
+
+@dataclass
+class Point(Geometry):
+    x: float
+    y: float
+    z: float
+    
+    def toCommonGeometryObject(self):
+        point_ = CommonGeometryMessages.Point(x=self.x, y=self.y, z=self.z)
+        geometry_ = CommonGeometryMessages.Geometry(point=point_)
+        return geometry_
+
+@dataclass
+class Polyline(Geometry):
+    points: list[Point]
+    
+    def toCommonGeometryObject(self):
+        points_ = [CommonGeometryMessages.Point(x=p.x, y=p.y, z=p.z) for p in self.points]
+        polyline_ = CommonGeometryMessages.Polyline(point=points_)
+        geometry_ = CommonGeometryMessages.Geometry(polyline=polyline_)
+        return geometry_
+
+@dataclass
+class Cube(Geometry):
+    """
+    Represents a 3D cube defined by two opposite corners and optional rotations.
+
+    The rotation angles (rotationAboutX, rotationAboutY, rotationAboutZ) are in degrees
+    and follow the **right-hand rule** for positive direction. i.e., positive rotation
+    is counterclockwise when looking along the axis toward the origin.
+    """
+    corner1: Point
+    corner2: Point
+    rotationAboutX: float = 0
+    rotationAboutY: float = 0
+    rotationAboutZ: float = 0
+
+    def toCommonGeometryObject(self):
+        corner1_ = CommonGeometryMessages.Point(x=self.corner1.x, y=self.corner1.y, z=self.corner1.z)
+        corner2_ = CommonGeometryMessages.Point(x=self.corner2.x, y=self.corner2.y, z=self.corner2.z)
+        box_ = CommonGeometryMessages.Box(corner1=corner1_, corner2=corner2_, rotationAboutX=self.rotationAboutX, rotationAboutY=self.rotationAboutY, rotationAboutZ=self.rotationAboutZ)
+        geometry_ = CommonGeometryMessages.Geometry(box=box_)
+        return geometry_
+    
+@dataclass
+class Cylinder(Geometry):
+    axisStartPoint: Point
+    axisEndPoint: Point
+    radius: float
+    
+    def toCommonGeometryObject(self):
+        axisStartPoint_ = CommonGeometryMessages.Point(x=self.axisStartPoint.x, y=self.axisStartPoint.y, z=self.axisStartPoint.z)
+        axisEndPoint_ = CommonGeometryMessages.Point(x=self.axisEndPoint.x, y=self.axisEndPoint.y, z=self.axisEndPoint.z)
+        radius_ = self.radius
+        cylinder_ = CommonGeometryMessages.Cylinder(axisStartPoint=axisStartPoint_, axisEndPoint=axisEndPoint_, radius=radius_)
+        geometry_ = CommonGeometryMessages.Geometry(cylinder=cylinder_)
+        return geometry_
+
+@dataclass
+class Sphere(Geometry):
+    center: Point
+    radius: float
+    
+    def toCommonGeometryObject(self):
+        center_ = CommonGeometryMessages.Point(x=self.center.x, y=self.center.y, z=self.center.z)
+        radius_ = self.radius
+        sphere_ = CommonGeometryMessages.Sphere(center=center_, radius=radius_)
+        geometry_ = CommonGeometryMessages.Geometry(sphere=sphere_)
+        return geometry_