photoneo_vision

로봇 측에서 Photoneo Bin Picking Studio(BPS) 1.11.0의 통신 프로토콜 (TCP/IP, 바이너리)에 접속해 Bin Picking 작업(초기화/스캔/트래젝토리 조회)과 솔루션 관리(변경/시작/중지/조회)를 수행하기 위한 Python 패키지입니다. ../MechMind/ (mechmind_vision)와 동일한 계층 구조 철학을 따르지만, Photoneo BPS는 ASCII가 아닌 바이너리·다중 채널 프로토콜이라 세부 구현은 다릅니다 — 자세한 배경은 docs/implementation_plan.md 참고.

빠른 시작 (pip으로 설치한 경우)

pip install rb-photoneo

pip install로 받으면 컴파일된 라이브러리(.so)와 타입 스텁(.pyi)만 포함됩니다 — .py 소스, config/, examples/, docs/는 패키지 안에 들어있지 않습니다(비공개 소스 배포 정책, 아래 "소스에서 개발하기" 참고). 설정은 YAML 파일 없이 PhotoneoConfig를 코드에서 직접 생성하세요:

from photoneo_vision import PhotoneoClient, PhotoneoConfig, Pose

config = PhotoneoConfig(
    host="192.168.1.1",
    vision_system_id=1,
    # 기본값은 RainbowRobotics "rzyx"와 동일한 ZYX_INTRINSIC.
    # 다른 로봇 브랜드면 rotation_formalism / brand_id_prefix를 바꾸세요
    # (지원 값: QUATERNION / XYZ_EXTRINSIC / ROTATION_VECTOR / ZYX_INTRINSIC).
)

with PhotoneoClient(config) as bps:
    bps.initialize_vision_system(start_joints=[...], end_joints=[...])  # 최초 1회

    # Hand-Eye 시스템: 로봇의 현재 TCP pose를 tool_offset(TCP의 flange 기준
    # 오프셋, 로봇의 tool-data 설정값)과 함께 넘기면 flange pose로 자동 변환됨.
    # flange pose를 직접 계산해 flange_pose=로 넘겨도 됨.
    bps.scan(
        tcp_pose=Pose(x=500, y=0, z=300, rx=0, ry=0, rz=0),
        tool_offset=Pose(x=0, y=0, z=150, rx=0, ry=0, rz=0),
    )

    trajectory = bps.get_trajectory()
    for segment in trajectory.segments:
        for wp in segment.waypoints:
            print(wp.joints)  # 6 joint values, degrees

Config 전체 옵션, 예제 스크립트, 프로토콜 레퍼런스 문서는 pip 패키지에 포함되어 있지 않으니 GitHub 레포에서 참고하세요: https://github.com/hyojoonlee04/Photoneo

아키텍처

robot program
     │
     ▼
vision/        AbstractVisionClient (ABC) ─ PhotoneoClient
     │                                          │
     ▼                                          ▼
protocol/      codec.py (encode/decode, 순수 함수)   transport/  PhotoneoTcpClient (Request-Response 채널 소켓 I/O)
                messages.py (Pose, TrajectoryResponse, ...)      StateServer (옵션, State Server 채널)
                constants.py (Request/Message/Error 코드)
                rotation.py (RotationFormalism별 Pose ↔ 4x4 변환)

• protocol/: I/O 없는 순수 인코딩/디코딩 함수 + 공용 데이터 타입.
• transport/: PhotoneoTcpClient(Request-Response, 포트 11003, BPS=서버), StateServer(State Server 채널, 포트 11004, 로봇 컨트롤러가 서버 — 옵션, 기본 비활성화).
• vision/: AbstractVisionClient ABC + PhotoneoClient 구현체.

소스에서 개발하기 (기여자용)

pip으로 그냥 설치해 쓰는 경우라면 이 섹션은 건너뛰고 위 "빠른 시작"을 참고하세요. 이 레포를 clone해서 소스를 직접 수정/빌드하려는 경우에만 필요합니다.

git clone https://github.com/hyojoonlee04/Photoneo.git
cd Photoneo
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

설정

config/default_config.yaml을 복사해 실제 장비 IP/포트/Vision System ID에 맞게 수정하세요.

photoneo:
  host: "192.168.1.1"
  request_port: 11003
  vision_system_id: 1
  rotation_formalism: "zyx_intrinsic"   # RainbowRobotics "rzyx"와 동일 포맷
  brand_id_prefix: "DOOSAN/1.11.0_"     # 실제 Brand ID는 Photoneo 지원팀과 확인 필요

Rotation Formalism: 이 패키지는 기본적으로 RainbowRobotics의 "rzyx" 오일러(수학적으로 ZYX_INTRINSIC과 동일 — 근거는 protocol/rotation.py 모듈 docstring)를 타깃으로 합니다. RainbowRobotics는 Photoneo가 공식 등재한 Brand ID 목록(Integrator Guide Appendix 2)에 없으므로, brand_id_prefix는 동일한 회전 포맷을 쓰는 DOOSAN/1.11.0_으로 placeholder 설정되어 있습니다 — 실기 연결 전 Photoneo 지원팀에 실제 인식 가능한 Brand ID 문자열을 확인하세요. RotationFormalism.QUATERNION/XYZ_EXTRINSIC/ROTATION_VECTOR도 지원되므로 다른 로봇 브랜드로 전환 시 rotation_formalism/brand_id_prefix만 바꾸면 됩니다.

사용법 (소스 clone 기준, YAML 설정 파일 사용)

from photoneo_vision import PhotoneoClient, PhotoneoConfig

config = PhotoneoConfig.from_yaml("config/local_config.yaml")
with PhotoneoClient(config) as bps:
    bps.initialize_vision_system(start_joints=[...], end_joints=[...])  # 4, 최초 1회
    bps.scan()                                                          # 1
    trajectory = bps.get_trajectory()                                  # 2
    for segment in trajectory.segments:
        for wp in segment.waypoints:
            print(wp.joints)  # 6 joint values, degrees
    for gripper in trajectory.gripper_commands:
        print(gripper.action)  # 1=Attach, 2=Detach, 3-5=User1-3

전체 예제:

• examples/connection_check.py — Initialize → Scan → Get Object Pose → Get Trajectory 순서로 호출하며 디코드 결과를 출력 (실기 연결 시 가장 먼저 실행할 진단 스크립트).
• examples/pick_and_place_demo.py — 전형적인 pick 루프.
• examples/solution_management_demo.py — 솔루션 조회/변경/시작/중지.
• examples/state_server_demo.py — State Server 옵션 기능 데모 (더미 관절값 콜백).

.venv/bin/python examples/connection_check.py config/local_config.yaml

State Server (옵션)

BPS 6장의 State Server 채널은 캘리브레이션/시각화 목적의 보조 채널로, 로봇 컨트롤러가 TCP 서버 역할을 하며 관절/툴포즈를 10Hz 이상 스트리밍해야 합니다. 기본적으로 비활성화되어 있으며(config.state_server.enabled=False), 활성화하려면 실제 로봇의 현재 관절값/툴포즈를 반환하는 콜백을 transport.state_server.StateServer에 연결해야 합니다:

from photoneo_vision import StateServer, Pose
from photoneo_vision.protocol.constants import pad_brand_id

def pose_provider():
    return robot.get_joint_positions_deg(), robot.get_tool_pose_mm_deg()  # -> (list[float], Pose)

server = StateServer(
    bind_host="0.0.0.0", port=11004,
    brand_id=pad_brand_id(config.brand_id_prefix),
    formalism=config.rotation_formalism,
    pose_provider=pose_provider,
)
server.start()  # 데몬 스레드
...
server.stop()

명령/프로토콜 레퍼런스

• docs/protocol_reference.md — Request ID 표, 바이트 레이아웃, Rotation Formalism/Brand ID, mm↔m 단위 변환 규칙, 확인됨/ 미확인 표기.
• docs/implementation_plan.md — 이 패키지를 설계할 때의 배경/범위 결정 기록.

구현 범위는 8개 요청(Initialize Vision System, Scan, Get Object Pose, Trajectory, Change/Start/Stop Solution, Get Running Solution)으로 한정되어 있습니다 — Capture/Reuse Scan/Pick Failed/Get Status/Change Bounding Box/ Calibration 4종/Communication Check는 미구현이며, protocol/constants.py의 RequestID에 참고용으로만 값이 남아 있습니다.

테스트

.venv/bin/pytest

test_codec.py는 Integrator Guide의 hex 예시를 golden vector로 사용해 바이트 단위로 인코딩/디코딩을 검증합니다. test_tcp_client.py/ test_photoneo_client.py/test_state_server.py는 로컬 fake TCP 서버를 띄워 실제 하드웨어 없이 전체 round-trip을 검증합니다.

주의: brand_id_prefix, mm/m 단위 가정(비-EXT_DEVICE 포맷), Get Object Pose의 payload size 불일치 등은 실장비로 검증되지 않았습니다 — 실기 연결 전 반드시 docs/protocol_reference.md의 "미확인" 항목을 examples/connection_check.py로 재확인하세요.