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）
• 単位：mm

座標変換

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

# 转换公式 (简化版)
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株式会社までお問い合わせください。