Release Candidate for three-python-library - 11.7.4

three/MF/V3/Descriptors/ProtocolInfo.py

@@ -0,0 +1,23 @@
+from typing import List
+
+
+class ProtocolInfo:
+    """
+    Desktop-processing protocol capability descriptor, returned by the
+    `GetProtocolInfo` task.  Lets a desktop engine detect what a connected
+    scanner supports and degrade gracefully against older firmware.
+    """
+    def __init__(self, version: int, capabilities: List[str] = None):
+        # Desktop-processing protocol version.
+        self.version = version
+        """
+        Capability tokens supported by this server.
+
+        Known capabilities:
+        - "scanCaptureStreaming": the server can stream raw scan captures to a
+        client for desktop processing (see the `SetProcessingDevices` task
+        and the `ScanCapture` descriptor).
+        """
+        self.capabilities = capabilities
+
+

three/MF/V3/Descriptors/ScanCapture.py

@@ -0,0 +1,36 @@
+class ScanCapture:
+    """
+    Raw scan capture image descriptor streamed to clients that process scans
+    themselves (`SetProcessingDevices` client processing).  Each stereo capture
+    is sent as two buffers, one per camera, described by this descriptor.
+
+    The buffer payload is the raw image data: `rows` rows of `step` bytes,
+    pixel format given by the OpenCV type code in `type`.
+    """
+    def __init__(self, rows: int, cols: int, type: int, step: int, camera: int, focus: int, index: int, orientation: int, frequency: int, phase: int, angle: float, texture: bool):
+        # Image rows.
+        self.rows = rows
+        # Image columns.
+        self.cols = cols
+        # OpenCV Mat type code (e.g. CV_8UC1).
+        self.type = type
+        # Row step in bytes.
+        self.step = step
+        # Camera index (0 or 1).
+        self.camera = camera
+        # Camera focus.
+        self.focus = focus
+        # Capture (turntable angle) index.
+        self.index = index
+        # Pattern orientation, or -1 for texture captures.
+        self.orientation = orientation
+        # Pattern frequency, or -1 for texture captures.
+        self.frequency = frequency
+        # Pattern phase, or -1 for texture captures.
+        self.phase = phase
+        # Turntable angle in radians.
+        self.angle = angle
+        # True if this is a texture capture.
+        self.texture = texture
+
+

three/MF/V3/Descriptors/ScannerList.py

@@ -0,0 +1,30 @@
+from typing import List
+
+
+class ScannerList:
+    """
+    Scanners discovered on the local network, returned by the
+    `DiscoverScanners` task.
+    """
+    class Scanner:
+
+        """
+         A discovered scanner.
+        """
+        def __init__(self, name: str, host: str, ip: str, port: int, version: str):
+            # The scanner's advertised name (e.g. "THREE").
+            self.name = name
+            # The scanner's mDNS host name (e.g. "matterandform.local").
+            self.host = host
+            # The scanner's IPv4 address.
+            self.ip = ip
+            # The scanner's server port.
+            self.port = port
+            # The scanner's advertised server version.  Empty if not advertised.
+            self.version = version
+
+    def __init__(self, scanners: List['Scanner'] = None):
+        # The discovered scanners.
+        self.scanners = scanners
+
+

three/MF/V3/Descriptors/ScannerStatus.py

@@ -0,0 +1,14 @@
+class ScannerStatus:
+    """
+    The desktop engine's scanner connection status.
+
+    Returned by the `GetScannerStatus` task and pushed to every client as a
+    `{"ScannerStatus": {...}}` message whenever the connection state changes.
+    """
+    def __init__(self, connected: bool, host: str):
+        # True if the engine is connected to a scanner.
+        self.connected = connected
+        # The connected scanner's host name or IP address.  Empty when not connected.
+        self.host = host
+
+

three/MF/V3/Descriptors/StorageInfo.py

@@ -0,0 +1,23 @@
+class StorageInfo:
+    """
+    Storage space of the desktop engine's local workspace and, when a scanner
+    is connected, of the scanner.  Returned by the `StorageInfo` task.
+    """
+    class Space:
+
+        """
+         Storage space of one side.
+        """
+        def __init__(self, available: int, capacity: int):
+            # Available bytes.
+            self.available = available
+            # Total capacity in bytes.
+            self.capacity = capacity
+
+    def __init__(self, local: 'Space', scanner: 'Space' = None):
+        # The engine's local workspace storage.
+        self.local = local
+        # The connected scanner's storage.  Absent when no scanner is connected.
+        self.scanner = scanner
+
+

three/MF/V3/Descriptors/__init__.py

@@ -7,9 +7,14 @@
 from MF.V3.Descriptors.Merge import * 
 from MF.V3.Descriptors.Project import * 
 from MF.V3.Descriptors.ProjectActions import * 
+from MF.V3.Descriptors.ProtocolInfo import * 
 from MF.V3.Descriptors.RemoveVertices import * 
+from MF.V3.Descriptors.ScanCapture import * 
 from MF.V3.Descriptors.ScanData import * 
+from MF.V3.Descriptors.ScannerList import * 
+from MF.V3.Descriptors.ScannerStatus import * 
 from MF.V3.Descriptors.Software import * 
+from MF.V3.Descriptors.StorageInfo import * 
 from MF.V3.Descriptors.System import * 
 from MF.V3.Descriptors.Transform import * 
 from MF.V3.Descriptors.VideoFrame import * 

three/MF/V3/Tasks/ConnectScanner.py

@@ -0,0 +1,61 @@
+from MF.V3.Task import TaskState as MF_V3_Task_TaskState
+
+
+class ConnectScanner:
+    """*
+    Connect the desktop engine to a scanner (desktop engine only).
+
+    The engine negotiates capabilities with `GetProtocolInfo`, enables client
+    processing, and downloads the scanner's calibration into its local
+    workspace.  A `ScannerStatus` message is pushed to every client when the
+    connection state changes.
+
+    > Request example:
+
+    ```json
+    {
+    "Task":{ "Index":1, "Type":"ConnectScanner", "Input":"matterandform.local" }
+    }
+    ```
+
+    > Response example:
+
+    ```json
+    {
+    "Task":{ "Index":1, "Type":"ConnectScanner", "Output":true, "State":"Completed" }
+    }
+    ```
+    """
+    class Request:
+
+        """
+         Client request for the `ConnectScanner` task.
+        """
+        def __init__(self, Index: int, Type: str, Input: str):
+            # A unique identifier generated by the client.
+            self.Index = Index
+            # "ConnectScanner"
+            self.Type = Type
+            # The scanner host name or IPv4 address.
+            self.Input = Input
+
+    class Response:
+
+        """
+         Server response for the `ConnectScanner` task.
+        """
+        def __init__(self, Index: int, Type: str, Output: bool = None, State: MF_V3_Task_TaskState = None, Error: str = None):
+            # The unique identifier generated by the client.
+            self.Index = Index
+            # "ConnectScanner"
+            self.Type = Type
+            # True if the connection was established.
+            self.Output = Output
+            # The current state of the task.
+            self.State = State
+            # A string describing the error if the task has failed.
+            self.Error = Error
+
+    def __init__(self):
+        pass
+

three/MF/V3/Tasks/DisconnectScanner.py

@@ -0,0 +1,54 @@
+from MF.V3.Task import TaskState as MF_V3_Task_TaskState
+
+
+class DisconnectScanner:
+    """*
+    Disconnect the desktop engine from its scanner (desktop engine only).
+
+    > Request example:
+
+    ```json
+    {
+    "Task":{ "Index":1, "Type":"DisconnectScanner" }
+    }
+    ```
+
+    > Response example:
+
+    ```json
+    {
+    "Task":{ "Index":1, "Type":"DisconnectScanner", "Output":true, "State":"Completed" }
+    }
+    ```
+    """
+    class Request:
+
+        """
+         Client request for the `DisconnectScanner` task.
+        """
+        def __init__(self, Index: int, Type: str):
+            # A unique identifier generated by the client.
+            self.Index = Index
+            # "DisconnectScanner"
+            self.Type = Type
+
+    class Response:
+
+        """
+         Server response for the `DisconnectScanner` task.
+        """
+        def __init__(self, Index: int, Type: str, Output: bool = None, State: MF_V3_Task_TaskState = None, Error: str = None):
+            # The unique identifier generated by the client.
+            self.Index = Index
+            # "DisconnectScanner"
+            self.Type = Type
+            # Always true.
+            self.Output = Output
+            # The current state of the task.
+            self.State = State
+            # A string describing the error if the task has failed.
+            self.Error = Error
+
+    def __init__(self):
+        pass
+

three/MF/V3/Tasks/DiscoverScanners.py

@@ -0,0 +1,65 @@
+from MF.V3.Descriptors.ScannerList import ScannerList
+from MF.V3.Task import TaskState as MF_V3_Task_TaskState
+
+
+class DiscoverScanners:
+    """*
+    Discover scanners on the local network (desktop engine only).
+
+    The engine browses mDNS for advertised scanners and additionally resolves
+    the default scanner host name, so scanners running older firmware that does
+    not advertise a service record are still found.  The search runs for a few
+    seconds before the result is returned; run the task again to refresh.
+
+    > Request example:
+
+    ```json
+    {
+    "Task":{ "Index":1, "Type":"DiscoverScanners" }
+    }
+    ```
+
+    > Response example:
+
+    ```json
+    {
+    "Task":{
+    "Index":1,
+    "Type":"DiscoverScanners",
+    "Output":{ "scanners":[{ "name":"THREE", "host":"matterandform.local", "ip":"192.168.50.115", "port":8081 }] },
+    "State":"Completed"
+    }
+    }
+    ```
+    """
+    class Request:
+
+        """
+         Client request for the `DiscoverScanners` task.
+        """
+        def __init__(self, Index: int, Type: str):
+            # A unique identifier generated by the client.
+            self.Index = Index
+            # "DiscoverScanners"
+            self.Type = Type
+
+    class Response:
+
+        """
+         Server response for the `DiscoverScanners` task.
+        """
+        def __init__(self, Index: int, Type: str, Output: ScannerList = None, State: MF_V3_Task_TaskState = None, Error: str = None):
+            # The unique identifier generated by the client.
+            self.Index = Index
+            # "DiscoverScanners"
+            self.Type = Type
+            # The discovered scanners.
+            self.Output = Output
+            # The current state of the task.
+            self.State = State
+            # A string describing the error if the task has failed.
+            self.Error = Error
+
+    def __init__(self):
+        pass
+

three/MF/V3/Tasks/DownloadScannerProject.py

@@ -0,0 +1,59 @@
+from MF.V3.Task import TaskState as MF_V3_Task_TaskState
+
+
+class DownloadScannerProject:
+    """*
+    Download a project archive from the connected scanner (desktop engine
+    only).
+
+    The archive is sent to the client as a task buffer whose descriptor is the
+    suggested file name.  The counterpart of `DownloadProject`, which archives a
+    local project.
+
+    > Request example:
+
+    ```json
+    {
+    "Task":{ "Index":1, "Type":"DownloadScannerProject", "Input":2 }
+    }
+    ```
+
+    > Response example:
+
+    ```json
+    {
+    "Task":{ "Index":1, "Type":"DownloadScannerProject", "State":"Completed" }
+    }
+    ```
+    """
+    class Request:
+
+        """
+         Client request for the `DownloadScannerProject` task.
+        """
+        def __init__(self, Index: int, Type: str, Input: int):
+            # A unique identifier generated by the client.
+            self.Index = Index
+            # "DownloadScannerProject"
+            self.Type = Type
+            # The scanner project index to download.
+            self.Input = Input
+
+    class Response:
+
+        """
+         Server response for the `DownloadScannerProject` task.
+        """
+        def __init__(self, Index: int, Type: str, State: MF_V3_Task_TaskState = None, Error: str = None):
+            # The unique identifier generated by the client.
+            self.Index = Index
+            # "DownloadScannerProject"
+            self.Type = Type
+            # The current state of the task.
+            self.State = State
+            # A string describing the error if the task has failed.
+            self.Error = Error
+
+    def __init__(self):
+        pass
+