racs-python 0.0.2__tar.gz → 0.3.0__tar.gz

{racs_python-0.0.2 → racs_python-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: racs-python
-Version: 0.0.2
+Version: 0.3.0
 Summary: Client library to access racs api server
 Author-email: Jonas Ahlf <javerik@javerik.space>
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -349,55 +349,127 @@ Keywords: racs,aravis,camera,client,api,genicam,gev,gigevision
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.7
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests>=2.31
 Requires-Dist: pydantic>=2.0
+Requires-Dist: websocket-client>=1.6
+Provides-Extra: numpy
+Requires-Dist: numpy; extra == "numpy"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: numpy; extra == "test"
 Dynamic: license-file
 
 # RACS python client library
 
-Simple client which uses `requests` to interact with the [racs-api server](https://codeberg.org/javerik/RACS-RustAravisCamServe).
+Client for the [racs-api server](https://codeberg.org/javerik/RACS-RustAravisCamServe): device
+discovery and connection, typed GenICam feature access, single frames, the live stream
+(WebSocket) and burst jobs.
 
 ## Install
 
 ```shell
-pip install racs-python
+pip install racs-python            # numpy is optional:
+pip install "racs-python[numpy]"   # adds Frame.to_numpy()
 ```
 
 ## Usage
 
 > **Make sure an instance of racs-api server is running**
 
+A `Camera` holds the device id, so nothing else needs to pass it around:
+
 ```python
 from racs_python import RacsClient
 
-client = RacsClient("http://localhost:8742/api/v1")
+client = RacsClient("http://localhost:8742")   # "/api/v1" is added to a bare server URL
 
-# discover devices
-devices = client.get_devices()
+devices = client.get_devices()                 # network discovery
 print(f"Found {len(devices.available)} available devices.")
 
-if devices.available:
-        target_id = devices.available[0].id
-        
-        # 2. Connection
-        client.connect_device(target_id)
-        print(f"Connected to device {target_id}")
+cam = client.connect(devices.available[0].id)  # or client.connect(5, ip="192.168.0.10")
 
-        # 3. Read/Write Settings
-        width = client.get_device_gc_node_value(target_id, "Width")
-        print(f"Current Width: {width}")
-        
-        client.set_device_gc_node_value(target_id, "Width", "1920")
+# Features are read and written as Python values
+print(cam["Width"])                            # 1280 (int)
+cam["ExposureTime"] = 5000.0
+cam["ReverseX"] = True
+width, height = cam.get_many("Width", "Height").values()
+cam.execute("TriggerSoftware")
+
+# Single frames
+with open("frame.jpg", "wb") as f:
+    f.write(cam.grab_jpeg(quality=90))
+frame = cam.grab_raw()                         # Mono8, with width/height
+pixels = frame.to_numpy()                      # (height, width) uint8
+
+cam.disconnect()
+```
+
+Already connected devices: `client.cameras()`, or `client.camera(id)` for a handle without a request.
+
+### Live stream
+
+The stream holds the camera until it is closed. Features can still be read and written while it
+runs; a change of size arrives as a new `stream.info` and applies to the frames after it.
+
+```python
+from itertools import islice
+
+with cam.live(format="raw", pixel_depth="mono16", fps=10) as stream:
+    for frame in islice(stream, 100):
+        pixels = frame.to_numpy()              # uint16 at bit_depth > 8
+        print(frame.frame_number, frame.dropped, frame.bit_depth, pixels.mean())
+```
+
+`format="jpeg"` (the default) delivers JPEG files in `frame.data`. A stream that the server ends
+because of an error raises `LiveStreamError`; `cam.stream_error()` reports the last one.
 
-        # 4. Grab an image
-        jpg_data = client.grab_jpg_frame(target_id)
-        with open("frame.jpg", "wb") as f:
-            f.write(jpg_data)
+### Packet size
 
-        # 5. Cleanup
-        client.disconnect_device(target_id)
+Every grab, stream and burst uses the camera's stream packet size (`GevSCPSPacketSize`, bytes per
+packet including IP and UDP headers) as it is. Jumbo frames such as 7960 need a link MTU of 9000.
 
+```python
+info = cam.packet_size()                       # packet_size, min/max/inc, link_mtu, interface
+cam["GevSCPSPacketSize"] = 7960                # a multiple of info.inc, not above the link MTU
+auto = cam.auto_packet_size()                  # the largest size whose test packets arrive
+```
+
+Both work during a live stream, which pauses briefly and carries on with the new size
+(`stream.info.packet_size`).
+
+### Burst jobs
+
+A burst grabs up to 500 frames on the server in the background. Leaving the `with` block deletes
+the job and its frames.
+
+```python
+with cam.burst(50, format="raw", pixel_depth="mono16") as job:
+    for frame in job.frames():                 # yields each frame as soon as it is captured
+        ...
+    info = job.wait()                          # final status
 ```
+
+`job.image(i)` returns the encoded bytes of one frame, `job.images()` lists what has been
+captured, and `cam.job(job_id)` re-attaches to a job by id.
+
+### Errors
+
+Every error is a `RacsError`. HTTP errors are `RacsHttpError` (a `requests.HTTPError`) with
+`status_code` and `body`; the specific ones are `CameraBusyError` (the camera is held by a stream,
+burst or grab), `NotFoundError` and `ImageFailedError`. Feature reads raise `FeatureError`, a
+failed burst `BurstJobFailedError`.
+
+### Low-level client
+
+`RacsClient` maps one method onto each REST route and takes the device id every time, e.g.
+`client.get_device_gc_node_value(0, "Width")` or `client.start_grab_job(0, 20, "raw")`. Values
+are strings there, exactly as the server sends them.
+
+## Tests
+
+`client_libs/run-tests.sh python` builds the repository's fake-camera server
+(`cargo run --example fake_server`), starts it and runs the tests against it. `pytest` on its own
+runs only the tests that need no server.

racs_python-0.3.0/README.md

@@ -0,0 +1,111 @@
+# RACS python client library
+
+Client for the [racs-api server](https://codeberg.org/javerik/RACS-RustAravisCamServe): device
+discovery and connection, typed GenICam feature access, single frames, the live stream
+(WebSocket) and burst jobs.
+
+## Install
+
+```shell
+pip install racs-python            # numpy is optional:
+pip install "racs-python[numpy]"   # adds Frame.to_numpy()
+```
+
+## Usage
+
+> **Make sure an instance of racs-api server is running**
+
+A `Camera` holds the device id, so nothing else needs to pass it around:
+
+```python
+from racs_python import RacsClient
+
+client = RacsClient("http://localhost:8742")   # "/api/v1" is added to a bare server URL
+
+devices = client.get_devices()                 # network discovery
+print(f"Found {len(devices.available)} available devices.")
+
+cam = client.connect(devices.available[0].id)  # or client.connect(5, ip="192.168.0.10")
+
+# Features are read and written as Python values
+print(cam["Width"])                            # 1280 (int)
+cam["ExposureTime"] = 5000.0
+cam["ReverseX"] = True
+width, height = cam.get_many("Width", "Height").values()
+cam.execute("TriggerSoftware")
+
+# Single frames
+with open("frame.jpg", "wb") as f:
+    f.write(cam.grab_jpeg(quality=90))
+frame = cam.grab_raw()                         # Mono8, with width/height
+pixels = frame.to_numpy()                      # (height, width) uint8
+
+cam.disconnect()
+```
+
+Already connected devices: `client.cameras()`, or `client.camera(id)` for a handle without a request.
+
+### Live stream
+
+The stream holds the camera until it is closed. Features can still be read and written while it
+runs; a change of size arrives as a new `stream.info` and applies to the frames after it.
+
+```python
+from itertools import islice
+
+with cam.live(format="raw", pixel_depth="mono16", fps=10) as stream:
+    for frame in islice(stream, 100):
+        pixels = frame.to_numpy()              # uint16 at bit_depth > 8
+        print(frame.frame_number, frame.dropped, frame.bit_depth, pixels.mean())
+```
+
+`format="jpeg"` (the default) delivers JPEG files in `frame.data`. A stream that the server ends
+because of an error raises `LiveStreamError`; `cam.stream_error()` reports the last one.
+
+### Packet size
+
+Every grab, stream and burst uses the camera's stream packet size (`GevSCPSPacketSize`, bytes per
+packet including IP and UDP headers) as it is. Jumbo frames such as 7960 need a link MTU of 9000.
+
+```python
+info = cam.packet_size()                       # packet_size, min/max/inc, link_mtu, interface
+cam["GevSCPSPacketSize"] = 7960                # a multiple of info.inc, not above the link MTU
+auto = cam.auto_packet_size()                  # the largest size whose test packets arrive
+```
+
+Both work during a live stream, which pauses briefly and carries on with the new size
+(`stream.info.packet_size`).
+
+### Burst jobs
+
+A burst grabs up to 500 frames on the server in the background. Leaving the `with` block deletes
+the job and its frames.
+
+```python
+with cam.burst(50, format="raw", pixel_depth="mono16") as job:
+    for frame in job.frames():                 # yields each frame as soon as it is captured
+        ...
+    info = job.wait()                          # final status
+```
+
+`job.image(i)` returns the encoded bytes of one frame, `job.images()` lists what has been
+captured, and `cam.job(job_id)` re-attaches to a job by id.
+
+### Errors
+
+Every error is a `RacsError`. HTTP errors are `RacsHttpError` (a `requests.HTTPError`) with
+`status_code` and `body`; the specific ones are `CameraBusyError` (the camera is held by a stream,
+burst or grab), `NotFoundError` and `ImageFailedError`. Feature reads raise `FeatureError`, a
+failed burst `BurstJobFailedError`.
+
+### Low-level client
+
+`RacsClient` maps one method onto each REST route and takes the device id every time, e.g.
+`client.get_device_gc_node_value(0, "Width")` or `client.start_grab_job(0, 20, "raw")`. Values
+are strings there, exactly as the server sends them.
+
+## Tests
+
+`client_libs/run-tests.sh python` builds the repository's fake-camera server
+(`cargo run --example fake_server`), starts it and runs the tests against it. `pytest` on its own
+runs only the tests that need no server.

{racs_python-0.0.2 → racs_python-0.3.0}/pyproject.toml

@@ -4,19 +4,20 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "racs-python"
-version = "0.0.2"
+version = "0.3.0"
 authors = [
     { name="Jonas Ahlf", email="javerik@javerik.space" },
 ]
 description = "Client library to access racs api server"
 readme = "README.md"
-requires-python = ">=3.7"
+requires-python = ">=3.9"
 license = { file = "LICENSE" }
 
 # Added specific version constraints for stability
 dependencies = [
     "requests>=2.31",
-    "pydantic>=2.0"  # Required for the code provided (V2)
+    "pydantic>=2.0",  # Required for the code provided (V2)
+    "websocket-client>=1.6"  # Live stream
 ]
 
 classifiers = [
@@ -29,4 +30,11 @@ keywords = ["racs", "aravis", "camera", "client", "api", "genicam", "gev", "gige
 
 [project.urls]
 "Homepage" = "https://codeberg.org/javerik/RACS-RustAravisCamServe"
-"Bug Tracker" = "https://codeberg.org/javerik/RACS-RustAravisCamServe/issues"
+"Bug Tracker" = "https://codeberg.org/javerik/RACS-RustAravisCamServe/issues"
+
+[project.optional-dependencies]
+numpy = ["numpy"]  # Frame.to_numpy()
+test = ["pytest", "numpy"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

racs_python-0.3.0/src/racs_python/__init__.py

@@ -0,0 +1,41 @@
+from .burst import BurstJob
+from .camera import Camera
+from .client import RacsClient
+from .errors import (
+    BurstJobFailedError,
+    CameraBusyError,
+    FeatureError,
+    ImageFailedError,
+    LiveStreamError,
+    NotFoundError,
+    RacsError,
+    RacsHttpError,
+)
+from .frame import Frame
+from .live import LiveStream
+from .models import (
+    AutoPacketSize,
+    BurstFormat,
+    BurstJobCreated,
+    BurstJobInfo,
+    DeviceConnections,
+    DeviceDiscoverInfo,
+    FeatureState,
+    GenICamAccessMode,
+    GenICamEnumInfo,
+    GenICamNodeCategory,
+    GenICamNodeInfo,
+    GenICamNodeType,
+    GenICamVisibility,
+    ImageEntryFailed,
+    ImageEntryOk,
+    JobStatus,
+    LiveFormat,
+    OnFailure,
+    PacketSizeInfo,
+    PixelDepth,
+    StreamErrorInfo,
+    StreamInfo,
+)
+
+__version__ = "0.3.0"

racs_python-0.3.0/src/racs_python/burst.py

@@ -0,0 +1,119 @@
+import time
+from typing import TYPE_CHECKING, Iterator, List, Optional, Union
+from uuid import UUID
+
+from .errors import BurstJobFailedError, NotFoundError, RacsError
+from .frame import Frame
+from .models import BurstJobInfo, ImageEntry, ImageEntryOk, JobStatus
+
+if TYPE_CHECKING:
+    from .camera import Camera
+
+
+class BurstJob:
+    """
+    A burst job on the server. The frames stay there until the job is deleted, or expire 10 min
+    after it finishes.
+
+    Used as a context manager, the job is deleted on exit::
+
+        with cam.burst(20, format="raw") as job:
+            for frame in job.frames():
+                ...
+    """
+
+    def __init__(self, camera: "Camera", job_id: Union[UUID, str]):
+        self.camera = camera
+        self.id = job_id if isinstance(job_id, UUID) else UUID(str(job_id))
+        # The first status that carried the frame geometry; it is the same for every frame.
+        self._geometry: Optional[BurstJobInfo] = None
+
+    @property
+    def _client(self):
+        return self.camera.client
+
+    def info(self) -> BurstJobInfo:
+        """The job's status and progress."""
+        info = self._client.get_grab_job(self.camera.id, self.id)
+        if info.width is not None:
+            self._geometry = info
+        return info
+
+    def images(self) -> List[ImageEntry]:
+        """Every frame attempted so far, in capture order: ImageEntryOk or ImageEntryFailed."""
+        return self._client.list_grab_job_images(self.camera.id, self.id)
+
+    def image(self, index: int) -> bytes:
+        """The encoded bytes of frame ``index``."""
+        return self._client.get_grab_job_image(self.camera.id, self.id, index)
+
+    def frame(self, index: int) -> Frame:
+        """Frame ``index`` with its geometry, ready for :meth:`Frame.to_numpy` (raw jobs)."""
+        data = self.image(index)
+        geometry = self._geometry or self.info()
+        if geometry.width is None or geometry.height is None:
+            raise RacsError(f"burst job {self.id} reports no frame geometry")
+        return Frame(
+            data=data,
+            width=geometry.width,
+            height=geometry.height,
+            format=geometry.format.value,
+            pixel_format=geometry.pixel_format or "Mono8",
+            bit_depth=geometry.bit_depth or 8,
+        )
+
+    def wait(self, timeout: Optional[float] = None, poll_interval: float = 0.1) -> BurstJobInfo:
+        """
+        Block until the job is completed or cancelled and return its final status. Raises
+        BurstJobFailedError if it failed and TimeoutError after ``timeout`` seconds.
+        """
+        deadline = None if timeout is None else time.monotonic() + timeout
+        while True:
+            info = self.info()
+            if info.status.is_terminal:
+                if info.status == JobStatus.FAILED:
+                    raise BurstJobFailedError(info)
+                return info
+            if deadline is not None and time.monotonic() >= deadline:
+                raise TimeoutError(f"burst job {self.id} still {info.status.value} after {timeout} s")
+            time.sleep(poll_interval)
+
+    def frames(self, poll_interval: float = 0.1) -> Iterator[Frame]:
+        """
+        Yield every captured frame in order, as soon as it is on the server; failed frames (only
+        with ``on_failure="skip"``) are left out. Ends when the job is done, and raises
+        BurstJobFailedError after the last frame if the job failed.
+        """
+        next_index = 0
+        while True:
+            # Status first: once it is terminal, the listing that follows is complete.
+            info = self.info()
+            for entry in self.images():
+                if entry.index < next_index:
+                    continue
+                next_index = entry.index + 1
+                if isinstance(entry, ImageEntryOk):
+                    yield self.frame(entry.index)
+            if info.status.is_terminal:
+                if info.status == JobStatus.FAILED:
+                    raise BurstJobFailedError(info)
+                return
+            time.sleep(poll_interval)
+
+    def delete(self) -> None:
+        """Cancel the job if it still runs, and drop it and its frames from the server."""
+        self._client.delete_grab_job(self.camera.id, self.id)
+
+    cancel = delete
+
+    def __enter__(self) -> "BurstJob":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        try:
+            self.delete()
+        except NotFoundError:
+            pass
+
+    def __repr__(self) -> str:
+        return f"BurstJob(device_id={self.camera.id}, id='{self.id}')"