خلاصه (Summary)

OAK Select CHOP ترکیبی از یک Script CHOP، یک Select CHOP و سایر CHOPهای وابسته به سخت‌افزار است.
عملکرد پایه‌ی آن به این شکل است که یک OAK Device CHOP و یک نام استریم (stream name) به آن معرفی می‌شود.

در ساده‌ترین حالت، داده‌های استریم به‌صورت کانال‌هایی با نام‌گذاری مناسب در CHOP نمایش داده می‌شوند.
برای مثال، پیام‌های ImgDetections که شامل مختصات دوبعدی (2D) و برچسب اشیای شناسایی‌شده هستند، بدون نیاز به هیچ کدنویسی دستی، مستقیماً به‌صورت کانال‌های CHOP ظاهر می‌شوند.

در سناریوهای پیچیده‌تر، مانند ردیابی لندمارک‌های دست، ممکن است نوع استریم از جنس NNData یا Buffer باشد.
در این حالت، کاربر باید یک callback پیاده‌سازی کرده و داده‌ها را به‌صورت دستی پردازش (parse) کند.

فهرست مطالب (Contents)

  1. Summary

  2. Parameters – OAK Page

  3. Parameters – Common Page

  4. Operator Inputs

  5. Info CHOP Channels
     5.1 Common CHOP Info Channels
     5.2 Common Operator Info Channels
     5.3 Script CHOP Functionality
     5.4 Queue Size
     5.5 Max Items
     5.6 Output Format
     5.7 Use First Sample Only
     5.8 Info CHOP
     5.9 See Also

پارامترها – صفحه OAK (Parameters – OAK Page)

Active
active – تعیین می‌کند که آیا OAK Select CHOP پردازش (cook) شود یا خیر.

OAK Device CHOP
chop – یک OAK Device CHOP که در حال اجرای یک pipeline از depthai است.

Stream
stream – نام استریمی که قرار است دریافت شود.

Queue Size
queuesize – این پارامتر برای بهینه‌سازی مصرف حافظه استفاده می‌شود و تعداد پیام‌هایی را که TouchDesigner هنگام دریافت پیام از OAK بازاستفاده می‌کند مشخص می‌کند.
(به بخش «Queue Size» در ادامه مراجعه کنید.)

Max Items
maxitems – این پارامتر کمک می‌کند OAK Select CHOP همیشه تعداد ثابتی کانال خروجی تولید کند.
برای مثال، در pipeline تشخیص تصویر، تعداد آیتم‌های شناسایی‌شده در هر فریم متفاوت است، اما ما می‌خواهیم خروجی TouchDesigner از نظر تعداد کانال‌ها ثابت باقی بماند.

Output Format
outputformat – ⊞
گزینه‌ی پیش‌فرض Items As Separate Channels، امکان Time-Slicing را فعال می‌کند،
در حالی که Items as Separate Samples این قابلیت را ندارد.

اگر استریمی دارید که به‌صورت خودکار CHOP را پر می‌کند، حالت Items as Separate Samples روش مناسبی برای این است که CHOP همواره به‌طور ثابت Max Items سمپل خروجی داشته باشد.

Use First Sample Only
firstsample – فقط از جدیدترین پیام دریافت‌شده استفاده می‌کند.
برای مثال، در یک استریم IMU با نرخ فریم بسیار بالا، فعال‌سازی این گزینه باعث می‌شود تنها آخرین سمپل نمایش داده شود.

Sample Rate
rate – نرخ نمونه‌برداری CHOP. مقدار پیش‌فرض برابر با me.time.rate است.

Callbacks DAT
callbacks – DATای که callbackها در آن تعریف شده‌اند.

Setup Parameters
setuppars – با کلیک روی این دکمه، تابع callback مربوط به setupParameters() اجرا می‌شود.

پارامترها – صفحه Common (Parameters – Common Page)

Time Slice
timeslice – فعال‌سازی این گزینه باعث می‌شود کانال‌ها به‌صورت Time Slice پردازش شوند.
Time Slice فاصله‌ی زمانی بین آخرین فریم cook و فریم cook فعلی است.

Scope
scope – برای تعیین اینکه کدام کانال‌ها تحت تأثیر قرار بگیرند، برخی CHOPها از رشته‌ی Scope در صفحه Common استفاده می‌کنند.

Sample Rate Match
srselect – ⊞
برای مدیریت شرایطی که چند CHOP ورودی نرخ نمونه‌برداری متفاوت دارند.
در صورت Resampling، منحنی‌ها بر اساس روش Interpolation تعیین‌شده (یا Linear به‌صورت پیش‌فرض) درون‌یابی می‌شوند.

Export Method
exportmethod – ⊞
مشخص می‌کند اتصال کانال CHOP به پارامتر به چه شکلی انجام شود.
برای اطلاعات بیشتر به مستندات Export مراجعه کنید.

Export Root
autoexportroot – مسیر ریشه‌ای که همه‌ی exportهایی که به‌صورت Channel Name → Path:Parameter انجام می‌شوند، نسبت به آن تعریف می‌شوند.

Export Table
exporttable – DATای که اطلاعات export را هنگام استفاده از روش DAT Table Export نگه می‌دارد.

ورودی‌های اپراتور (Operator Inputs)

کانال‌های Info CHOP

اطلاعات اضافی مربوط به OAK Select CHOP از طریق Info CHOP قابل دسترسی است.

کانال‌های عمومی Info در CHOP

  • start – شروع بازه CHOP بر حسب سمپل

  • length – تعداد سمپل‌های CHOP

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

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

  • time_slice – اگر Time Slice فعال باشد مقدار 1

  • export_sernum – تعداد دفعات به‌روزرسانی اتصال‌های export

کانال‌های عمومی Info اپراتور

  • total_cooks – تعداد دفعاتی که اپراتور از شروع پردازش cook شده است

  • cook_time – مدت زمان آخرین cook بر حسب میلی‌ثانیه

  • cook_frame – شماره فریم آخرین cook نسبت به تایم‌لاین کامپوننت

  • cook_abs_frame – شماره فریم آخرین cook نسبت به زمان مطلق

  • cook_start_time – زمان شروع cook در آن فریم (میلی‌ثانیه)

  • cook_end_time – زمان پایان cook در آن فریم (میلی‌ثانیه)

  • cooked_this_frame – اگر اپراتور در این فریم cook شده باشد مقدار 1

  • warnings – تعداد هشدارها

  • errors – تعداد خطاها

Script CHOP Functionality (قابلیت‌های مشابه Script CHOP)

OAK Select CHOP از چند جهت رفتار مشابه Script CHOP دارد.
یک callback به نام onSetupParameters وجود دارد که در آن می‌توان پارامترهای سفارشی اضافه کرد.

همچنین در callbackهای دیگر مانند:

  • onReceiveNNData

  • onReceiveBuffer

  • onReceiveSystemInformation

می‌توان کانال‌ها را اضافه کرده و داده‌ها را در آن‌ها نوشت.

هنگام پیاده‌سازی callback سفارشی (مانند مثال زیر)، اگر بخواهید Time-Slicing را غیرفعال کنید یا تعداد سمپل‌های خروجی را تعیین کنید، باید مقدار Output Format روی Items as Separate Samples تنظیم شده باشد.

import depthai as dai
def onReceiveNNData(oakSelectOp, oakNnData: dai.NNData):
oakSelectOp.clear()
oakSelectOp.appendChan('foo')
oakSelectOp.numSamples = 1 # Output Format must be "Items as Separate Samples"
oakSelectOp['foo'][0] = 42
return

Queue Size

پارامتر Queue Size به TouchDesigner کمک می‌کند هم از نگه‌داشتن تعداد زیادی پیام جلوگیری کند و هم حافظه را برای حداقل تعداد پیام‌ها بازاستفاده کند.

برای مثال، مقدار 2 انتخاب مناسبی است، چون:

  • TouchDesigner می‌تواند یک پیام را به کاربر نمایش دهد

  • هم‌زمان یک پیام دیگر به‌صورت asynchronous با داده‌ی جدید پر شود

اما اگر استریم دارای نرخ فریم بالا باشد (مثل داده‌های IMU)، مقدار Queue Size باید حداقل دو برابر تعداد پیام‌هایی باشد که انتظار دارید در یک فریم TouchDesigner دریافت شوند.

اگر TouchDesigner یک فریم ویدیویی را از دست بدهد، در cook بعدی لازم است دو برابر پیام‌های معمول پردازش شوند؛ بنابراین Queue Size باید حداقل دو برابر باشد.

Max Items

برخی پیام‌ها را می‌توان به‌صورت «آیتم» توصیف کرد.
برای مثال، ImgDetections می‌تواند شامل:

  • item0

  • item1

  • item2
    و … باشد.

برای این نوع استریم‌ها، داشتن تعداد ثابتی کانال در OAK Select CHOP مفید است، حتی اگر در آخرین پیام دریافتی برخی آیتم‌ها وجود نداشته باشند.

Output Format

فرمت خروجی پیش‌فرض Items as Separate Channels است.
برای مثال، هنگام دریافت ImgDetections از MobileNet، هر detection به ۶ کانال نیاز دارد:

  • confidence

  • label

  • xmin

  • xmax

  • ymin

  • ymax

در نتیجه، تعداد کل کانال‌ها برابر است با:
۶ × Max Items

در این حالت Time-Slicing فعال است و تعداد سمپل‌ها بسته به وضعیت Time Slice تغییر می‌کند.

اگر حاضر باشید Time-Slicing را فدا کنید، می‌توانید Output Format را روی Items as Separate Samples قرار دهید.
در این حالت، پیام‌های جدید به‌شکل ۶ کانال × Max Items سمپل مرتب می‌شوند؛
یعنی هر ImgDetection معادل یک سمپل در CHOP خواهد بود.

دلیل دیگر استفاده از این حالت زمانی است که callbackهایی مانند onReceiveNNData پیاده‌سازی کرده‌اید و نیاز دارید تعداد سمپل‌ها را به‌صورت دستی تعیین کنید (oakSelectOp.numSamples = 1).

Use First Sample Only

مشابه Shuffle CHOP، این پارامتر باعث می‌شود فقط جدیدترین پیام دریافت‌شده استفاده شود.
برای مثال، در یک استریم IMU با نرخ فریم بسیار بالا، فعال‌سازی این گزینه مشابه استفاده از Trim CHOP در حالت Absolute است تا فقط آخرین سمپل نمایش داده شود.

Info CHOP

وقتی OAK Select CHOP به یک Info CHOP متصل شود، علاوه بر کانال‌های معمول مربوط به cook، چند کانال اختصاصی OAK نیز نمایش داده می‌شود:

  • sequence_num – مطابق با sequenceNum در مستندات depthai

  • messages_received – تعداد کل پیام‌های دریافت‌شده با نام استریم تعیین‌شده

  • fps – نرخ فریم مؤثر این استریم؛ یعنی سرعتی که TouchDesigner پیام‌ها را دریافت می‌کند
    (این مقدار با FPS هدف استریم تفاوت دارد)