wlsonar 0.1.0__tar.gz

wlsonar-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.3
+Name: wlsonar
+Version: 0.1.0
+Summary: Python client and Range Image Protocol utilities for Water Linked Sonar 3D-15.
+Author: Water Linked
+Requires-Dist: protobuf>=5.29.5
+Requires-Dist: python-snappy>=0.7.3
+Requires-Dist: requests>=2.32.4
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# wlsonar
+
+Package wlsonar is a python client library for the Water Linked [Sonar 3D-15](https://www.waterlinked.com/shop/wl-21045-2-sonar-3d-15-689).
+
+The key features of this package are:
+
+- `wlsonar.Sonar3D` for configuration and inspection of system state.
+- `wlsonar.range_image_protocol` for [Range Image Protocol](https://docs.waterlinked.com/sonar-3d/sonar-3d-15-api/#range-image-protocol-rip2) packets.
+
+## Installation 
+
+The wlsonar package is hosted on pypi and can be installed with pip:
+
+```bash
+pip install wlsonar
+```
+
+## Quickstart
+
+Following is a snippet showing how to connect to the sonar and receive images.
+
+```python
+import wlsonar
+import wlsonar.range_image_protocol as rip
+
+# (set to your sonar's IP address
+ip = "10.1.2.24"
+
+# connect, enable acoustics, configure to send images over UDP multicast
+sonar = wlsonar.Sonar3D(ip)
+sonar.set_acoustics_enabled(True)
+sonar.set_udp_multicast()
+
+print("Sonar configured, listening for UDP packets...")
+
+# receive UDP packets, parse them into protobuf, and extract voxels
+sock = wlsonar.open_sonar_udp_socket()
+try:
+    while True:
+        packet, _ = sock.recvfrom(wlsonar.UDP_MAX_DATAGRAM_SIZE)
+        try:
+            msg = rip.unpackb(packet)
+        except rip.UnknownProtobufTypeError:
+            continue
+        if isinstance(msg, rip.RangeImage):
+            xyz = wlsonar.range_image_to_xyz(msg)
+            id = msg.header.sequence_id
+            print(f"Got range image {id} with {len(xyz)} voxels")
+finally:
+    sock.close()
+```
+
+More elaborate examples can be found in [the examples folder](./examples/).
+
+## Documentation and resources
+
+Documentation for this package is provided in the form of:
+
+- Elaborate examples in [the examples folder](./examples/).
+- Tests in [the tests folder](./tests).
+- Docstrings in code.
+
+For general documentation about the Sonar 3D-15 see: https://docs.waterlinked.com/sonar-3d/sonar-3d-15/. The integration API that this package interfaces with is documented here: https://docs.waterlinked.com/sonar-3d/sonar-3d-15-api/. See also the replayer: https://sonar.replay.waterlinked.com/.
+
+## Development and testing
+
+`uv` is required for development of the package. Run the following to set up the project:
+
+```bash
+uv sync
+```
+
+### Linting
+
+The package is linted with `ruff` and `mypy`:
+
+```bash
+uv run ruff check
+uv run ruff format --diff
+uv run mypy .
+```
+
+### Testing
+
+The package is tested with pytest:
+
+```bash
+uv run pytest
+```
+
+There are also end-to-end (e2e) tests to verify the package against a real Sonar 3D-15. Make sure to read the documentation of [tests/test_e2e_real_sonar.py](tests/test_e2e_real_sonar.py), then run the e2e test with:
+
+```bash
+uv run pytest -m e2e -s --sonar-ip <sonar ip>
+```
+
+### Versioning
+
+Versioning is handled with `uv`. Setting a new version with `uv version <new version>` and merging to master will build a new version on pypi. We follow semantic versioning.
+
+### Protobuf
+
+The Sonar 3D-15 uses a .proto file to define message formats. This package includes generated Python for these messages. When changing the .proto file, run the following to generate new Python code:
+
+```bash
+uv run protoc \
+    --proto_path=src/wlsonar/range_image_protocol/_proto/ \
+    --python_out=src/wlsonar/range_image_protocol/_proto/ \
+    --mypy_out=src/wlsonar/range_image_protocol/_proto/  \
+    src/wlsonar/range_image_protocol/_proto/WaterLinkedSonarIntegrationProtocol.proto
+```

wlsonar-0.1.0/README.md

@@ -0,0 +1,111 @@
+# wlsonar
+
+Package wlsonar is a python client library for the Water Linked [Sonar 3D-15](https://www.waterlinked.com/shop/wl-21045-2-sonar-3d-15-689).
+
+The key features of this package are:
+
+- `wlsonar.Sonar3D` for configuration and inspection of system state.
+- `wlsonar.range_image_protocol` for [Range Image Protocol](https://docs.waterlinked.com/sonar-3d/sonar-3d-15-api/#range-image-protocol-rip2) packets.
+
+## Installation 
+
+The wlsonar package is hosted on pypi and can be installed with pip:
+
+```bash
+pip install wlsonar
+```
+
+## Quickstart
+
+Following is a snippet showing how to connect to the sonar and receive images.
+
+```python
+import wlsonar
+import wlsonar.range_image_protocol as rip
+
+# (set to your sonar's IP address
+ip = "10.1.2.24"
+
+# connect, enable acoustics, configure to send images over UDP multicast
+sonar = wlsonar.Sonar3D(ip)
+sonar.set_acoustics_enabled(True)
+sonar.set_udp_multicast()
+
+print("Sonar configured, listening for UDP packets...")
+
+# receive UDP packets, parse them into protobuf, and extract voxels
+sock = wlsonar.open_sonar_udp_socket()
+try:
+    while True:
+        packet, _ = sock.recvfrom(wlsonar.UDP_MAX_DATAGRAM_SIZE)
+        try:
+            msg = rip.unpackb(packet)
+        except rip.UnknownProtobufTypeError:
+            continue
+        if isinstance(msg, rip.RangeImage):
+            xyz = wlsonar.range_image_to_xyz(msg)
+            id = msg.header.sequence_id
+            print(f"Got range image {id} with {len(xyz)} voxels")
+finally:
+    sock.close()
+```
+
+More elaborate examples can be found in [the examples folder](./examples/).
+
+## Documentation and resources
+
+Documentation for this package is provided in the form of:
+
+- Elaborate examples in [the examples folder](./examples/).
+- Tests in [the tests folder](./tests).
+- Docstrings in code.
+
+For general documentation about the Sonar 3D-15 see: https://docs.waterlinked.com/sonar-3d/sonar-3d-15/. The integration API that this package interfaces with is documented here: https://docs.waterlinked.com/sonar-3d/sonar-3d-15-api/. See also the replayer: https://sonar.replay.waterlinked.com/.
+
+## Development and testing
+
+`uv` is required for development of the package. Run the following to set up the project:
+
+```bash
+uv sync
+```
+
+### Linting
+
+The package is linted with `ruff` and `mypy`:
+
+```bash
+uv run ruff check
+uv run ruff format --diff
+uv run mypy .
+```
+
+### Testing
+
+The package is tested with pytest:
+
+```bash
+uv run pytest
+```
+
+There are also end-to-end (e2e) tests to verify the package against a real Sonar 3D-15. Make sure to read the documentation of [tests/test_e2e_real_sonar.py](tests/test_e2e_real_sonar.py), then run the e2e test with:
+
+```bash
+uv run pytest -m e2e -s --sonar-ip <sonar ip>
+```
+
+### Versioning
+
+Versioning is handled with `uv`. Setting a new version with `uv version <new version>` and merging to master will build a new version on pypi. We follow semantic versioning.
+
+### Protobuf
+
+The Sonar 3D-15 uses a .proto file to define message formats. This package includes generated Python for these messages. When changing the .proto file, run the following to generate new Python code:
+
+```bash
+uv run protoc \
+    --proto_path=src/wlsonar/range_image_protocol/_proto/ \
+    --python_out=src/wlsonar/range_image_protocol/_proto/ \
+    --mypy_out=src/wlsonar/range_image_protocol/_proto/  \
+    src/wlsonar/range_image_protocol/_proto/WaterLinkedSonarIntegrationProtocol.proto
+```

wlsonar-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "wlsonar"
+version = "0.1.0"
+description = "Python client and Range Image Protocol utilities for Water Linked Sonar 3D-15."
+readme = "README.md"
+authors = [
+    { name = "Water Linked" }
+]
+requires-python = ">=3.8"
+dependencies = [
+    "protobuf>=5.29.5",
+    "python-snappy>=0.7.3",
+    "requests>=2.32.4",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.15,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.mypy]
+warn_return_any = true
+disallow_untyped_defs = true
+
+[dependency-groups]
+dev = [
+    "mypy>=1.14.1",
+    "mypy-protobuf>=3.7.0",
+    "pdbpp>=0.11.7",
+    "pillow>=10.4.0",
+    "pytest>=8.3.5",
+    "ruff>=0.14.8",
+]
+
+[[tool.mypy.overrides]]
+module = ["requests.*", "snappy.*"]
+follow_untyped_imports = true
+
+[tool.ruff]
+line-length = 100
+exclude = [
+    "*_pb2.py",
+    "*_pb2.pyi",
+]
+
+
+[tool.ruff.format]
+quote-style = "double"
+line-ending = "auto"
+
+
+[tool.ruff.lint]
+select = [
+    "D",   # pydocstyle
+    "F",   # pyflakes
+    "E",   # pycodestyle
+    "I",   # isort
+    "ANN", # flake8 type annotations
+    "RUF", # ruff-specific rules
+]
+fixable = ["ALL"]
+ignore = [
+    "D107", # undocumented-public-init
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*.py" = ["D"]
+"test_*.py" = ["D"]
+
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.pytest.ini_options]
+markers = [
+    "e2e: end-to-end tests that require real sonar hardware. Skipped by default.",
+]
+addopts = "-m 'not e2e'"

wlsonar-0.1.0/src/wlsonar/__init__.py

@@ -0,0 +1,27 @@
+"""Package wlsonar.
+
+Package wlsonar provides a python client and Range Image Protocol utilities for Water Linked
+Sonar 3D-15.
+"""
+
+from ._client import (
+    DEFAULT_MCAST_GRP,
+    DEFAULT_MCAST_PORT,
+    FALLBACK_IP,
+    UDP_MAX_DATAGRAM_SIZE,
+    Sonar3D,
+    UdpConfig,
+)
+from ._udp_helper import open_sonar_udp_socket
+from ._xyz_helper import range_image_to_xyz
+
+__all__ = [
+    "DEFAULT_MCAST_GRP",
+    "DEFAULT_MCAST_PORT",
+    "FALLBACK_IP",
+    "UDP_MAX_DATAGRAM_SIZE",
+    "Sonar3D",
+    "UdpConfig",
+    "open_sonar_udp_socket",
+    "range_image_to_xyz",
+]