griip-sdk 0.1.0__tar.gz

griip_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: griip-sdk
+Version: 0.1.0
+Summary: GRIIP SDK: hardware control and orchestration for bin picking
+License: Proprietary
+Keywords: Vention,GRIIP,SDK,Robot,Gripper,Automation
+Author: VentionCo
+Requires-Python: >=3.10,<3.11
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Requires-Dist: PyYAML (>=6.0,<7.0)
+Requires-Dist: defusedxml (>=0.7.1,<0.8.0)
+Requires-Dist: grpcio (>=1.78.0)
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: numpy (>=1.24)
+Requires-Dist: omegaconf (>=2.3.0,<3.0.0)
+Requires-Dist: opencv-python-headless (>=4.9.0,<5.0.0)
+Requires-Dist: paho-mqtt (>=2.1.0,<3.0.0)
+Requires-Dist: protobuf (>=4.0)
+Requires-Dist: pydantic (>=2.12.5,<3.0.0)
+Requires-Dist: pymodbus (>=3.12.1,<4.0.0)
+Requires-Dist: scipy (>=1.11.0,<2.0)
+Requires-Dist: spatialmath-python (>=1.1.15,<2.0.0)
+Requires-Dist: toppra (>=0.6.0)
+Requires-Dist: trimesh (>=4.11,<5.0)
+Requires-Dist: urchin (>=0.0.30,<0.0.31)
+Requires-Dist: vention-firmware-grpc-client (>=1.0.0)
+Description-Content-Type: text/markdown
+
+# griip-sdk
+
+Python SDK for hardware control and orchestration of gripper-based bin picking on Vention's MachineMotion platform.
+
+## Installation
+
+```bash
+pip install griip-sdk
+```
+
+## Prerequisites for hardware control
+
+`griip-sdk` depends on two private wheels that are not on PyPI. Install them manually from GitHub Releases before using hardware features:
+
+```bash
+# vamp_planner
+pip install "https://github.com/VentionCo/platform-products/releases/download/vamp-wheel-v0.6.1-20260313/vamp_planner-<version>-cp310-cp310-linux_aarch64.whl"
+
+# foundationstereoclient
+pip install "https://github.com/VentionCo/platform-products/releases/download/foundationstereoclient/v1.11.0/foundationstereoclient-<version>-cp310-cp310-linux_aarch64.whl"
+```
+
+> These manual steps are temporary. Both packages will eventually become MachineMotion-side services, at which point this step goes away.
+
+## Quickstart
+
+```python
+from griip_sdk import BaseGripper, GripperMoveResult, Robotiq2F140Gripper
+
+gripper = Robotiq2F140Gripper(host="<machineMotion-ip>")
+result: GripperMoveResult = gripper.move(position=0.5)
+```
+
+## What's NOT shipped on PyPI
+
+The demo runners under `griip_sdk.prototyping.run_*` import `mmai_griip_api` (the gRPC service). They are not part of the public API and will fail to import unless `mmai-griip-api` is installed alongside the SDK (e.g. via the Debian package on a MachineMotion).
+
+## Releases
+
+Versioning is hand-bumped semver. Bump `version` in `pyproject.toml` before triggering the PyPI publish workflow (`publish-griip-sdk-pypi.yml`).
+

griip_sdk-0.1.0/README.md

@@ -0,0 +1,40 @@
+# griip-sdk
+
+Python SDK for hardware control and orchestration of gripper-based bin picking on Vention's MachineMotion platform.
+
+## Installation
+
+```bash
+pip install griip-sdk
+```
+
+## Prerequisites for hardware control
+
+`griip-sdk` depends on two private wheels that are not on PyPI. Install them manually from GitHub Releases before using hardware features:
+
+```bash
+# vamp_planner
+pip install "https://github.com/VentionCo/platform-products/releases/download/vamp-wheel-v0.6.1-20260313/vamp_planner-<version>-cp310-cp310-linux_aarch64.whl"
+
+# foundationstereoclient
+pip install "https://github.com/VentionCo/platform-products/releases/download/foundationstereoclient/v1.11.0/foundationstereoclient-<version>-cp310-cp310-linux_aarch64.whl"
+```
+
+> These manual steps are temporary. Both packages will eventually become MachineMotion-side services, at which point this step goes away.
+
+## Quickstart
+
+```python
+from griip_sdk import BaseGripper, GripperMoveResult, Robotiq2F140Gripper
+
+gripper = Robotiq2F140Gripper(host="<machineMotion-ip>")
+result: GripperMoveResult = gripper.move(position=0.5)
+```
+
+## What's NOT shipped on PyPI
+
+The demo runners under `griip_sdk.prototyping.run_*` import `mmai_griip_api` (the gRPC service). They are not part of the public API and will fail to import unless `mmai-griip-api` is installed alongside the SDK (e.g. via the Debian package on a MachineMotion).
+
+## Releases
+
+Versioning is hand-bumped semver. Bump `version` in `pyproject.toml` before triggering the PyPI publish workflow (`publish-griip-sdk-pypi.yml`).

griip_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[tool.poetry]
+name = "griip-sdk"
+version = "0.1.0"
+description = "GRIIP SDK: hardware control and orchestration for bin picking"
+authors = ["VentionCo"]
+license = "Proprietary"
+readme = "README.md"
+keywords = ["Vention", "GRIIP", "SDK", "Robot", "Gripper", "Automation"]
+classifiers = [
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3.10",
+]
+packages = [{ include = "griip_sdk", from = "src" }]
+
+[tool.poetry.dependencies]
+python = ">=3.10,<3.11"
+grpcio = ">=1.78.0"
+numpy = ">=1.24"
+protobuf = ">=4.0"
+toppra = ">=0.6.0"
+pydantic = "^2.12.5"
+omegaconf = "^2.3.0"
+pymodbus = "^3.12.1"
+urchin = "^0.0.30"
+trimesh = "^4.11"
+defusedxml = "^0.7.1"
+spatialmath-python = "^1.1.15"
+httpx = "^0.28.1"
+paho-mqtt = "^2.1.0"
+opencv-python-headless = "^4.9.0"
+scipy = ">=1.11.0,<2.0"
+PyYAML = "^6.0"
+vention-firmware-grpc-client = ">=1.0.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.4"
+pytest-cov = "6.3.0"
+
+[tool.ruff]
+line-length = 140
+
+[tool.pytest.ini_options]
+testpaths = ["src"]
+
+[build-system]
+requires = ["poetry-core>=2.0.0"]
+build-backend = "poetry.core.masonry.api"

griip_sdk-0.1.0/src/griip_sdk/__init__.py

@@ -0,0 +1,4 @@
+from griip_sdk.hardware.gripper import BaseGripper, GripperMoveResult
+from griip_sdk.hardware.robotiq_2f140_gripper import Robotiq2F140Gripper
+
+__all__ = ["BaseGripper", "GripperMoveResult", "Robotiq2F140Gripper"]

griip_sdk-0.1.0/src/griip_sdk/calibration/cartesian_pose.py

@@ -0,0 +1,219 @@
+from typing import List, Union, Optional
+from griip_sdk.calibration.units import AngleUnit, DistanceUnit, Meters, MetersQuaternions
+from scipy.spatial.transform import Rotation as ScipyRotation  # type: ignore
+import numpy as np
+import math
+from dataclasses import dataclass
+from spatialmath import SE3, SO3, UnitQuaternion
+
+
+NumpyNumber = Union[np.float64, np.float32, np.int64, np.int32]
+
+
+# for the vision api.
+def to_float_array(items: List[Union[float, NumpyNumber]]) -> List[float]:
+    return list(map(lambda a: float(a), items))
+
+
+@dataclass
+class Point:
+    # xyz point
+    x: Meters
+    y: Meters
+    z: Meters
+
+    @staticmethod
+    def from_array(xyz: Union[List[Meters], np.ndarray]) -> "Point":
+        return Point(xyz[0], xyz[1], xyz[2])
+
+    def to_array(self) -> List[Meters]:
+        return [self.x, self.y, self.z]
+
+    def to_vector(self) -> np.ndarray:
+        return np.array(self.to_array())
+
+    # returns a new point, with value x + add_shift.x, y + add_shift.y, ...
+    # does not modify existing.
+    def translate(self, add_shift: "Point") -> "Point":
+        a = self.to_vector()
+        b = add_shift.to_vector()
+        return Point.from_array(a + b)
+
+
+class CartesianPose:
+    pose: SE3
+    position: Point
+    rotation: SO3
+
+    CAMERA_ANGLE_UNIT = AngleUnit.Radians
+    CAMERA_DISTANCE_UNIT = DistanceUnit.Meters
+
+    def __init__(self, position: Point, rotation: SO3):
+        if isinstance(rotation, ScipyRotation):
+            rotation = SO3(rotation.as_matrix())
+        self.pose = SE3.Rt(R=rotation, t=position.to_array())
+
+    @property
+    def position(self) -> Point:
+        return Point.from_array(self.pose.t)
+
+    @property
+    def rotation(self) -> SO3:
+        return self.pose.R
+
+    @staticmethod
+    def from_SE3(pose: SE3) -> "CartesianPose":
+        return CartesianPose(Point.from_array(pose.t), pose.R)
+
+    def to_SE3(self) -> SE3:
+        return SE3(self.to_homogeneous_matrix())
+
+    def __str__(self):
+        return f"CartesianPose({self.pose.strline('rpy/yxz')})"
+
+    def __repr__(self):
+        return str(self)
+
+    def invert(self) -> SE3:
+        return self.pose.inv()
+
+    def transform_to(self, from_frame: Optional[SE3], to_frame: Optional[SE3]) -> SE3:
+        # get homo. matrices.
+        bTc = self.pose
+        aTb = SE3()  # defaults
+        cTd = SE3()  # defaults.
+
+        if from_frame is not None:
+            aTb = from_frame
+        if to_frame is not None:
+            cTd = to_frame.inv()
+
+        # calculate the transformation matrix from the local frame to the target frame
+        aTd = aTb @ bTc @ cTd
+
+        # Convert the resulting transformation matrix to a CartesianPose
+        return aTd
+
+    def to_canonical_frame(self, from_frame: SE3) -> SE3:
+        # Transform the position
+        return self.transform_to(from_frame, None)
+
+    @staticmethod
+    def from_moveit(position_and_quat: MetersQuaternions) -> SE3:
+        # position_and_quat is [x, y, z, qx, qy, qz, qw]
+        pos = position_and_quat[:3]
+        quat = UnitQuaternion(s=position_and_quat[-1], v=position_and_quat[3:6])
+        return SE3.Rt(R=quat.SO3(), t=pos)
+
+    def to_moveit(self) -> MetersQuaternions:
+        pos = self.pose.t
+        quat = UnitQuaternion(self.pose.R).vec_xyzs
+        return to_float_array(pos + list(quat))
+
+    @staticmethod
+    def from_camera_units(pose_vector: List[Union[Meters, float]]) -> SE3:
+        """
+        Take a 6 dimensional pose vector in camera units and return a SE3 object.
+
+        Args:
+            pose_vector: A list of 6 elements representing the pose in camera units.
+                  The first three elements are the position (x, y, z) in meters.
+                  The last three elements are the rotation vector (rx, ry, rz) in radians or degrees
+                  depending on the CAMERA_ANGLE_UNIT setting.
+        Returns:
+            pose: A spatialmath SE3 object representing the pose.
+        """
+        pos = DistanceUnit.Convert(
+            pose_vector[:3],
+            from_unit=CartesianPose.CAMERA_DISTANCE_UNIT,
+            to_unit=DistanceUnit.Meters,
+        )
+        units = "deg" if CartesianPose.CAMERA_ANGLE_UNIT == AngleUnit.Degrees else "rad"
+
+        angle = np.linalg.norm(pose_vector[3:])
+        axis = pose_vector[3:] / angle if angle != 0 else np.array([1.0, 0.0, 0.0])
+
+        return SE3.Rt(R=SO3.AngleAxis(angle, axis, unit=units), t=pos)
+
+    def to_camera_units(self) -> List[Union[Meters, float]]:
+        """
+        Convert the CartesianPose to a 6 dimensional pose vector in camera units.
+
+        Returns:
+            pose_vector: A list of 6 floats representing the pose in camera units.
+                  The first three elements are the position (x, y, z) in meters.
+                  The last three elements are the rotation vector (rx, ry, rz) in radians or degrees
+                  depending on the CAMERA_ANGLE_UNIT setting.
+        """
+        rot_vec, pos_vec = self.pose.rtvec()
+        if CartesianPose.CAMERA_ANGLE_UNIT == AngleUnit.Degrees:
+            rot_vec = np.degrees(rot_vec)
+
+        return to_float_array(list(pos_vec) + list(rot_vec))
+
+    @staticmethod
+    def from_homogeneous_matrix(homogeneous_matrix: np.ndarray) -> SE3:
+        return SE3(homogeneous_matrix)
+
+    def to_homogeneous_matrix(self) -> np.ndarray:
+        return self.pose.A
+
+    def diff(self, other: SE3):
+        """
+        Compute the rotational and translational difference between this pose and another pose.
+        Args:
+            other: Another CartesianPose to compare against.
+        Returns:
+            rotation_error_rad: The rotational difference in radians [0, pi].
+
+            translation_error: The translational difference in meters.
+        """
+        # Angular distance [0, pi] between two rotations.
+        rotation_error_rad = self.pose.angdist(other)
+        translation_error = np.linalg.norm(self.pose.t - other.t)
+        return rotation_error_rad, translation_error
+
+
+if __name__ == "__main__":
+    import math
+
+    def assert_float_array_eq(a1: List[float], a2: List[float]) -> None:
+        assert len(a1) == len(a1)
+        for i in range(len(a1)):
+            a, b = a1[i], a2[i]
+            assert math.isclose(a, b, rel_tol=1e-8)
+
+    def test_moveit_pose_conversions(move_it_pose: MetersQuaternions) -> None:
+        p = CartesianPose.from_moveit(move_it_pose)
+        camera_units_pose = p.to_camera_units()
+        p2 = CartesianPose.from_camera_units(camera_units_pose)
+        assert_float_array_eq(move_it_pose, p2.to_moveit())
+
+    def test_camera_pose_conversions(camera_units_pose: List[float]) -> None:
+        p = CartesianPose.from_camera_units(camera_units_pose)
+        move_it_pose = p.to_moveit()
+        p2 = CartesianPose.from_moveit(move_it_pose)
+        assert_float_array_eq(camera_units_pose, p2.to_camera_units())
+
+    test_camera_pose_conversions(
+        camera_units_pose=[
+            -0.36732380688872235,
+            0.31711499960934564,
+            -0.10696901055083409,
+            2.711732123419181,
+            1.505353005792903,
+            -0.07767478350482122,
+        ]
+    )
+
+    test_moveit_pose_conversions(
+        move_it_pose=[
+            -0.366833055335579,
+            0.32453574184240414,
+            -0.10696901055083409,
+            0.8738757958661387,
+            0.48511117474910254,
+            -0.025031275275235965,
+            0.01953655012953711,
+        ]
+    )

griip_sdk-0.1.0/src/griip_sdk/calibration/config_store.py

@@ -0,0 +1,114 @@
+"""File-based configuration store for calibration data.
+
+Reads versioned JSON files from /data/vention/calib_data/ (or a custom root).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+import tempfile
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_CALIBRATION_DATA_PATH = "/data/vention/calib_data"
+
+
+def _utc_ts() -> str:
+    return time.strftime("%Y-%m-%dT%H-%M-%SZ", time.gmtime())
+
+
+def _digest_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()[:16]
+
+
+def _atomic_write(path: Path, data: bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile(dir=path.parent, delete=False) as tmp:
+        tmp.write(data)
+        tmp.flush()
+        tmp_name = tmp.name
+    Path(tmp_name).replace(path)
+    os.chmod(path, 0o664)
+
+
+@dataclass(frozen=True)
+class VersionInfo:
+    name: str
+    version: str
+    path: Path
+    size: int
+
+
+class CalibrationConfigStore:
+    """Reads versioned JSON calibration files from a directory tree.
+
+    File layout:
+      root/
+        X_cam_flg__luxonis__18443010D1A8F71200__left/
+          2025-09-11T17-03-41Z__abcd1234.json
+        calibio__luxonis__18443010D1A8F71200/
+          2025-09-11T17-03-41Z__deadbeef.json
+    """
+
+    def __init__(self, root: Path | str = DEFAULT_CALIBRATION_DATA_PATH) -> None:
+        self.root = Path(root)
+
+    def format_filename(self, version: str, digest: str) -> str:
+        return f"{version}__{digest}.json"
+
+    @staticmethod
+    def format_config_name(*parts: str) -> str:
+        return "__".join(parts)
+
+    def add_new_version(self, name: str, data: Any) -> VersionInfo:
+        version = _utc_ts()
+        folder = self.root / name
+        payload = (json.dumps(data, indent=2, sort_keys=True) + "\n").encode("utf-8")
+        digest = _digest_bytes(payload)
+        filename = self.format_filename(version, digest)
+        path = folder / filename
+        if not path.exists():
+            _atomic_write(path, payload)
+        return VersionInfo(name=name, version=filename, path=path, size=path.stat().st_size)
+
+    def update_version(self, version_info: VersionInfo, data: Any) -> VersionInfo:
+        payload = (json.dumps(data, indent=2, sort_keys=True) + "\n").encode("utf-8")
+        _atomic_write(version_info.path, payload)
+        return VersionInfo(
+            name=version_info.name,
+            version=version_info.version,
+            path=version_info.path,
+            size=version_info.path.stat().st_size,
+        )
+
+    def load_latest(self, name: str) -> Any:
+        info = self._latest_info(name)
+        logger.info("Calibration store: loading latest '%s' from %s", name, info.path)
+        return self._load_path(info.path)
+
+    def list_versions(self, name: str) -> list[VersionInfo]:
+        folder = self.root / name
+        if not folder.exists():
+            return []
+        items = []
+        for json_path in sorted(folder.glob("*.json"), key=lambda path: path.name, reverse=True):
+            if json_path.is_file():
+                items.append(VersionInfo(name=name, version=json_path.name, path=json_path, size=json_path.stat().st_size))
+        return items
+
+    def _latest_info(self, name: str) -> VersionInfo:
+        versions = self.list_versions(name)
+        if not versions:
+            raise FileNotFoundError(f"No calibration versions found for '{name}' in {self.root / name}")
+        return versions[0]
+
+    def _load_path(self, path: Path) -> Any:
+        with path.open("r", encoding="utf-8") as file_handle:
+            return json.load(file_handle)

griip_sdk-0.1.0/src/griip_sdk/calibration/hand_eye_calib/README.md

@@ -0,0 +1,109 @@
+# Hand-Eye Calibration Module
+
+This module performs hand-eye calibration for robot-camera systems.
+
+## HTTP API Usage
+
+The calibration is exposed via an HTTP API.
+Configuration is loaded from `configs/robot_cells/<robot_cell>.yaml` which contains
+all robot, planner, and service URLs.
+
+### Calibrate
+
+```bash
+POST /calibration/hand-eye/calibrate
+Content-Type: application/json
+
+{
+    "robot_cell": "vp15_mcalpine",
+    "calibration_routine": "mcalpine_cell_routine.yaml",
+    "cam_name": "luxonis",
+    "sensor": "left"
+}
+```
+
+### Evaluate
+
+```bash
+POST /calibration/hand-eye/evaluate
+Content-Type: application/json
+
+{
+    "robot_cell": "vp15_mcalpine",
+    "calibration_routine": "mcalpine_cell_routine.yaml"
+}
+```
+
+### Status
+
+```bash
+GET /calibration/hand-eye/status
+```
+
+### Teach Mode (Set Home Position)
+
+Use teach mode to manually position the robot and save a new home position:
+
+```bash
+# 1. Start teach mode (enables freedrive)
+POST /calibration/hand-eye/teach/start
+Content-Type: application/json
+
+{
+    "robot_cell": "vp15_mcalpine",
+    "calibration_routine": "mcalpine_cell_routine.yaml"
+}
+
+# 2. Manually move the robot to desired home position...
+
+# 3. Check current position (optional)
+GET /calibration/hand-eye/teach/status
+
+# 4. Save the position and exit freedrive
+POST /calibration/hand-eye/teach/save
+
+# Or cancel without saving
+POST /calibration/hand-eye/teach/cancel
+```
+
+## Configuration
+
+The `robot_cell` parameter should match a config file in `configs/robot_cells/`:
+- `vp15_mcalpine` loads `configs/robot_cells/vp15_mcalpine.yaml`
+- `a10v_mcalpine` loads `configs/robot_cells/a10v_mcalpine.yaml`
+
+These configs include:
+- Robot settings (server_url, robot_ip, robot_model, cuboids)
+- Service URLs (curobo planner, vision server)
+- Motion planning settings (use_vamp)
+- Payload and gripper configuration
+
+## Requirements
+
+- Robot must be connected and VRMCS driver running
+- Motion planner server running (URL from config)
+- MMAI Vision camera server running (URL from config)
+- Charuco calibration board visible to camera
+
+## Python API Usage
+
+```python
+from griip_sdk.calibration.hand_eye_calib import HandEyeCalibrationService
+from griip_sdk.grpc_adapters.servicer_as_stub import ServicerAsStub
+
+calibrator = HandEyeCalibrationService(
+    robo=robot_client,
+    cam=camera_client,
+    store=config_store,
+    planning_stub=ServicerAsStub(planning_service),
+    config=calibration_routine_dict,
+    cam_intr=camera_intrinsics,
+    dist_coeffs=distortion_coefficients,
+    im_width=image_width,
+    im_height=image_height,
+    sensor_name="left",
+    save_dir="/data/calibration",
+)
+
+X_cam_flg = calibrator.calibrate()
+```

griip_sdk-0.1.0/src/griip_sdk/calibration/hand_eye_calib/__init__.py

@@ -0,0 +1,38 @@
+from griip_sdk.calibration.hand_eye_calib.core import (
+    Routine,
+    WaypointGenerator,
+    Waypoint,
+    project_points,
+    draw_points,
+    points_in_image,
+    invert_pose,
+    generate_camera_pose_on_sphere,
+)
+from griip_sdk.calibration.hand_eye_calib.routines import (
+    BootstrapRoutine,
+    SphereRoutine,
+)
+
+from griip_sdk.calibration.hand_eye_calib.main import (
+    HandEyeCalibrationService,
+    camera_vector_to_se3,
+    se3_to_camera_vector,
+    intrinsic_dict_to_arrays,
+)
+
+__all__ = [
+    "HandEyeCalibrationService",
+    "Routine",
+    "WaypointGenerator",
+    "Waypoint",
+    "BootstrapRoutine",
+    "SphereRoutine",
+    "project_points",
+    "draw_points",
+    "points_in_image",
+    "invert_pose",
+    "generate_camera_pose_on_sphere",
+    "camera_vector_to_se3",
+    "se3_to_camera_vector",
+    "intrinsic_dict_to_arrays",
+]

griip_sdk-0.1.0/src/griip_sdk/calibration/hand_eye_calib/config/routine.yaml

@@ -0,0 +1,9 @@
+# elevation, z rotation, radius
+calib_encircle:
+  - [70, -80, 0.57]
+  - [80, -70, 0.6]
+  - [70, 60, 0.64]
+  - [60, 0, 0.6]
+  - [50, 0, 0.6]
+
+eval_encircle: [70, 0, 0.6]