🧭 خلاصه (Summary)

Leap Motion CHOP داده‌های مربوط به دست، انگشت، ابزار (tool) و ژست‌ها (gestures) را از کنترلر Leap Motion می‌خواند. این نود، موقعیت‌ها و چرخش‌های دست/انگشت/ابزار و همچنین کانال‌های tracking (برای اعلام در حال ردیابی بودن) را خروجی می‌دهد. در حال حاضر فقط ۱ دستگاه Leap Motion هم‌زمان قابل اتصال است.

برای اتصال به دستگاه باید Ultraleap Tracking Software را نصب کنید. برای بهترین کارایی، در ویندوز از درایورهای Gemini v5.13.2+ و در مک از v5.14.0+ استفاده کنید:
https://developer.leapmotion.com/tracking-software-download
نسخه‌های قدیمی‌تر V2 یا V4 Orion نیز پشتیبانی می‌شوند. جزئیات را در پارامتر API ببینید.

علاوه بر نصب درایور، باید به TouchDesigner محل کتابخانه‌ی ردیابی را معرفی کنید:

  • ویندوز: با پارامتر Library Folder مسیر فایل LeapC.dll (برای Orion/Gemini) یا Leap.dll (برای Version 2/3) را مشخص کنید. این فایل‌ها در LeapSDK نصب می‌شوند و مسیرشان بسته به نسخه/گزینه‌های نصب متفاوت است.

  • macOS: مسیر را به اپلیکیشن Ultraleap Hand Tracking.app بدهید (پیش‌فرض: ‎/Applications/Ultraleap Hand Tracking.app‎). TouchDesigner فایل‌های کتابخانه را داخل محتوای برنامه به‌طور خودکار پیدا می‌کند.

نکته: در Gemini V5، Leap Motion فقط در یک جهت کار می‌کند. به‌طور پیش‌فرض، دست‌ها از پایین دید دوربین وارد می‌شوند؛ می‌توان این را در تنظیمات معکوس کرد. این با V2/V4 که می‌توانستند در هر دو جهت کار کنند، متفاوت است.

توجه: TouchDesigner شامل مجوز استفاده از سخت‌افزار/نرم‌افزار Leap Motion نیست. لطفاً درباره‌ی مجوزهای لازم پروژه‌تان با وب‌سایت UltraLeap بررسی کنید.

همچنین ببینید: Leap Motion, Leap Motion TOP

⚙️ پارامترها – صفحه Setup (Parameters – Setup Page)

  • Active (active): وقتی روشن باشد، داده از سنسور Leap Motion دریافت می‌شود.

  • API (api): انتخاب بین Leap Motion V2 یا V4/V5 برای ردیابی.
    V5 سریع‌تر و پایدارتر است؛ V2 برخی قابلیت‌های قدیمی مثل gestures را دارد.

  • Library Folder (libfolder) [Windows]: مسیر فایل DLL مطابق API انتخابی.

    • V4/V5: ‎LeapC.dll‎

    • V2: ‎Leap.dll‎
      برای Gemini V5: ابتدا نرم‌افزار را نصب کنید، سپس مسیر را به
      ‎C:\Program Files\Ultraleap\LeapSDK\lib\x64‎ بدهید تا LeapC.dll پیدا شود.

  • HMD Mode (hmd): سویچ به حالت Head Mounted Display.

  • Debug Channels (debugchannels): در صورت فعال‌بودن، کانال‌های زیر اضافه می‌شوند:

    • connected: اگر سنسور وصل است 1، در غیر این صورت 0.

    • sequence_id: شناسه یکتای فریم جاری.

  • Status Channels (statuschannels): در صورت فعال‌بودن، کانال‌های زیر اضافه می‌شوند:

    • hands / fingers / tools / gestures: تعداد دست/انگشت/ابزار/ژست شناسایی‌شده.

    • [hand/finger/tool/circle/swipe/keytap/screentap]:tracking = 1 اگر در حال ردیابی فعال باشد، وگرنه 0.

  • Named Hands (namedhands): نام‌گذاری کانال‌های دست به left (l) و right (r).

  • Hands (hands): تعداد دست‌ها. برای هر دست کانال‌های زیر اضافه می‌شود:

    • hand:t:* مختصات دست نسبت به سنسور.

    • hand:r:* چرخش دست.

  • Left Hands (lefthands) / Right Hands (righthands): هنگام استفاده از Named Hands تعداد دست‌های چپ/راست را تعیین کنید.

  • Hand Velocity (handvelocity): در صورت فعال‌بودن:

    • hand:v:* سرعت دست.

  • Hand Sphere (handsphere) [فقط API=V2]:

    • hand/sphere:t* موقعیت کره‌ی دست، hand/sphere:radius* شعاع.

  • Pinch Strength (pinchstrength): شدت چسبیدن شست و انگشت اشاره:

    • hand:pinch*

  • Grab Strength (grabstrength): شدت مشت شدن دست:

    • hand:grab* (0 = کف باز، 1 = مشت کامل)

  • Named Fingers (namedfingers): نام‌گذاری انگشت‌ها به thumb/index/middle/ring/pinky به‌جای شماره‌گذاری.

  • Fingers per Hand (fingersperhand): وقتی Named Fingers خاموش است، تعداد انگشت‌های هر دست.

  • Finger Rotation (fingerrotation): چرخش تمام انگشت‌ها:

    • hand/finger:r**

  • Finger Size (fingersize): در صورت فعال‌بودن:

    • hand/finger:length** و hand/finger:width**

  • Finger Extended (fingerextended): میزان صاف/کشیده بودن انگشت:

    • hand/finger:extended**

  • Finger Joints (fingerjoints): موقعیت تمام مفاصل هر انگشت:

    • hand/finger/joint_mcp:t**

    • hand/finger/joint_pip:t**

    • hand/finger/joint_dip:t**

    • hand/finger/joint_tip:t**

  • Tools (tools): تعداد ابزارها. برای هر ابزار:

    • tool:t**, tool:length, tool:width*

  • Circle Gestures (circlegestures): تعداد ژست‌های دایره‌ای. برای هر ژست:

    • circle:handindex* (به نکات پایین توجه کنید)

    • circle:t**، circle:radius، circle:progress* (تعداد چرخه‌ها)

  • Swipe Gestures (swipegestures): تعداد ژست‌های سوایپ. برای هر ژست:

    • swipe:handindex*, swipe:fingerindex* (نکات پایین)

    • swipe:t, *swipe:start, swipe:speed

  • Key Tap Gestures (keytapgestures): تعداد ژست‌های «ضربه کلیدی». برای هر ژست:

    • keytap:handindex*, keytap:fingerindex*

    • keytap:t*

  • Screen Tap Gestures (screentapgestures): تعداد ژست‌های «ضربه به صفحه» (حرکت سریع رو به جلو با انگشت/ابزار). برای هر ژست:

    • screentap:handindex*, screentap:fingerindex*

    • screentap:t*

نکات (NOTES):

  • ترتیب چرخش: Rx Ry Rz.

  • همه‌ی بردارها در دستگاه مختصات Leap داده می‌شوند.

  • برای ژست‌ها: اگر handindex = 1 باشد، کانال‌های با پیشوند hand1 داده‌های همان دست ژست را دارند. اگر handindex = -1 یعنی کانالی برای آن دست موجود نیست. برای fingerindex هم همین‌طور.

  • داده‌های همه‌ی پیشوندهای اندیسی (hand*, hand/finger*, …) تا وقتی سنسور آن‌ها را تشخیص می‌دهد، به همان دست/انگشت/ابزار/ژست اشاره خواهند کرد (ثابت می‌مانند).

  • محدودیت‌های تعداد دست/انگشت/ابزار/ژست باعث فیلتر شدن داده‌های اضافی می‌شود.

⚙️ پارامترهای مشترک – صفحه Common (Parameters – Common Page)

  • Time Slice (timeslice): خروجی time-sliced بین دو فریم cook.

  • Scope (scope): تعیین کانال‌های تحت تأثیر (الگوها/Pattern Matching).

  • Sample Rate Match (srselect): همسان‌سازی نرخ نمونه‌ی ورودی‌ها (بازنمونه‌برداری و روش درون‌یابی).

  • Export Method (exportmethod): روش اتصال کانال CHOP به پارامترها (DAT با اندیس/نام یا «Channel Name is Path:Parameter»).

  • Export Root (autoexportroot): ریشه‌ی مسیر برای حالت «Channel Name is Path:Parameter».

  • Export Table (exporttable): DAT حاوی اطلاعات اکسپورت هنگام استفاده از روش‌های DAT Table.

📊 کانال‌های Info (Info CHOP Channels)

ویژه‌ی Leap Motion CHOP (Specific):

  • installed

  • connected

  • hmd_policy_request

  • hmd_policy_actual

  • sequence_id

مشترک CHOP (Common CHOP Info Channels):

  • start — شروع بازه‌ی CHOP بر حسب نمونه

  • length — تعداد نمونه‌ها

  • sample_rate — نرخ نمونه‌برداری (فریم بر ثانیه)

  • num_channels — تعداد کانال‌ها

  • time_slice — 1 اگر Time Slice فعال است

  • export_sernum — شمار به‌روزرسانی‌های اتصال اکسپورت

مشترک اپراتور (Common Operator Info Channels):

  • total_cooks — تعداد cook از شروع پروسه

  • cook_time — مدت cook آخر (ms)

  • cook_frame / cook_abs_frame — شماره فریم cook (نسبت به تایم‌لاین کامپوننت/زمان مطلق)

  • cook_start_time / cook_end_time — زمان شروع/پایان cook در همان فریم (ms)

  • cooked_this_frame — آیا در این فریم cook شده است یا نه (0/1)

  • warnings / errors — تعداد هشدارها/خطاها