APIインターフェース仕様書

概要

本システムは完全なRESTful APIインターフェースを提供します。すべてのAPIルートは vision_arm_mcp/api/routes.py に統一的に定義され、FlaskのBlueprintを通じてWebサービスに登録されています。

ベースURL: http://localhost:5002

検出関連API

すべての測定データの取得

エンドポイント: GET /api/measurements

機能: 現在検出されているすべての物体の測定データを取得します。

レスポンス例:

{
  "measurements": [
    {
      "id": 1,
      "class": "red_shape",
      "confidence": 0.92,
      "position": {
        "x": 320,
        "y": 240
      },
      "distance_from_center": 150.2,
      "dimensions": {
        "width": 120,
        "height": 80
      },
      "quadrant": "第一象限",
      "timestamp": "2023-07-25T15:30:45"
    }
  ],
  "count": 1
}

特定の物体データの取得

エンドポイント: GET /api/measurements/<object_id>

パラメーター:

• object_id: 物体ID（整数）

レスポンス: 単一の物体の測定データ

ロボットアーム制御API

物体の把持

エンドポイント: POST /api/arm/catch_object

リクエストボディ:

{
  "image_x": 0.0,  // 物体相对于图像中心的X坐标
  "image_y": 0.0,  // 物体相对于图像中心的Y坐标
  "height_z": 50.0 // 抓取的目标Z高度
}

成功レスポンス (200):

{
  "status": "success",
  "message": "抓取动作已执行"
}

エラーレスポンス (400/500/503):

{
  "status": "error",
  "message": "错误描述"
}

物体の配置

エンドポイント: POST /api/arm/put_object

リクエストボディ:

{
  "image_x": 0.0,  // 目标放置位置相对于图像中心的X坐标
  "image_y": 0.0,  // 目标放置位置相对于图像中心的Y坐标
  "height_z": 60.0 // 放置的目标Z高度
}

レスポンス形式: 物体把持APIと同じです。

映像ストリームAPI

リアルタイム映像ストリーム

エンドポイント: GET /video_feed

機能: MJPEG形式のリアルタイム映像ストリームを取得します。

レスポンス: multipart/x-mixed-replace 形式の映像ストリーム

システム状態API

システム状態

エンドポイント: GET /api/status

機能: システムの稼働状態と設定情報を取得します。

レスポンス例:

{
  "status": "running",
  "version": "2.0.0",
  "services": {
    "web": "active",
    "mcp": "active",
    "detection": "active"
  },
  "config": {
    "model_path": "models/yolo11n_shape_detect.bin",
    "camera_device": "/dev/divisioncamera",
    "arm_serial_port": "/dev/ttyS1"
  }
}

エラー処理

共通エラー形式

{
  "status": "error",
  "message": "错误描述",
  "code": "ERROR_CODE",
  "timestamp": "2023-07-25T15:30:45"
}

主なエラーコード

座標系の説明

画像座標系

• 原点: 画像の中心
• X軸: 右方向が正、左方向が負
• Y軸: 上方向が正、下方向が負
• 単位: ピクセル

ロボットアーム座標系

• X軸: 前方向が正 (50-180mm)
• Y軸: 右方向が正 (-80-80mm)
• Z軸: 上方向が正 (-50-140mm)
• 単位: ミリメートル

座標変換

システムは画像座標からロボットアーム座標への変換を自動的に行います。

# 转换公式 (简化版)
arm_x = 0.821 * image_y + 114.2
arm_y = 0.3638 * image_x - 15.049

APIクライアントの例

Pythonの例

import requests

# 获取测量数据
response = requests.get('http://localhost:5002/api/measurements')
data = response.json()

# 控制机械臂抓取
payload = {
    "image_x": 100.0,
    "image_y": 50.0,
    "height_z": -50.0
}
response = requests.post('http://localhost:5002/api/arm/catch_object', json=payload)

curlの例

# 获取系统状态
curl http://localhost:5002/api/status

# 抓取物体
curl -X POST http://localhost:5002/api/arm/catch_object \
  -H "Content-Type: application/json" \
  -d '{"image_x": 100.0, "image_y": 50.0, "height_z": -50.0}'

レート制限

• ロボットアーム制御API: 1秒あたり最大1リクエスト
• 測定データAPI: 1秒あたり最大10リクエスト
• 映像ストリーム: 制限なし

認証

現在のバージョンでは認証は不要ですが、本番環境ではAPIキーまたはJWT認証を追加することをお勧めします。

お問い合わせ

資料のダウンロード・技術サポートについては、HumansX株式会社までお問い合わせください。