CPFIND("1")                          HUGIN                         CPFIND("1")


نام (NAME)
       cpfind - ابزار یافتن و تطبیق نقاط کنترل برای اتصال پانوراما

خلاصه دستور (SYNOPSIS)
       cpfind [گزینه‌ها] -o output_project project.pto

       cpfind [گزینه‌ها] -k i0 -k i1 [...] project.pto

       cpfind [گزینه‌ها] --kall project.pto

توضیحات (DESCRIPTION)
       دستور cpfind یک آشکارساز نقاط کنترل (Control-point) برای Hugin است. این
       برنامه یک فایل پروژه را به عنوان ورودی دریافت کرده و در صورت موفقیت، یک
       فایل پروژه حاوی نقاط کنترل ایجاد می‌کند. عملکرد آن به وجود اطلاعات معقول
       و دقیق لنز در فایل پروژه ورودی وابسته است.

       گام نخست، توصیف ویژگی‌ها است: در این گام، تصاویر فایل پروژه بارگذاری شده
       و نقاط کلیدی (Keypoints) جستجو می‌شوند. این نقاط نشان‌دهنده ویژگی‌های
       متمایز تصویر هستند.  cpfind از یک توصیف‌گر گرادیان‌محور برای توصیف
       ویژگی‌های نقاط کلیدی استفاده می‌کند.

       در گام دوم، یعنی تطبیق ویژگی‌ها، تمام نقاط کلیدی دو تصویر با یکدیگر
       تطبیق داده می‌شوند تا ویژگی‌های مشترک موجود در هر دو تصویر شناسایی شوند.
       در صورت موفقیت‌آمیز بودن این تطبیق، دو نقطه کلیدی از دو تصویر به یک نقطه
       کنترل تبدیل می‌شوند.

نحوه استفاده (USAGE)
   تصاویر خطی مستقیم و چشم‌ماهی (Rectilinear and fisheye images)
       ابزار Cpfind قادر به یافتن نقاط کنترل در تصاویر مستقیم (Rectilinear) و
       چشم‌ماهی (Fisheye) است. برای دستیابی به نقاط کنترل مناسب، تصاویری که
       میدان دید افقی بالایی دارند (مانند تصاویر فوق عریض مستقیم یا چشم‌ماهی)
       به یک فضای هم‌شکل (کانفورمال) تبدیل می‌شوند (cpfind از تصویربرداری
       استریوگرافیک استفاده می‌کند) و فرآیند تطبیق ویژگی‌ها در این فضا صورت
       می‌گیرد. پیش از ذخیره نقاط کنترل، مختصات مجدداً به فضای تصویر بازگردانده
       می‌شوند. این فرآیند به صورت خودکار و بر اساس اطلاعات لنز در فایل پروژه
       ورودی انجام می‌شود؛ بنابراین اطمینان حاصل کنید که فایل پروژه ورودی شامل
       اطلاعات معقولی درباره لنز مورد استفاده باشد.

   استفاده از سلست (Using celeste)
       پانوراماهای فضای باز اغلب حاوی ابر هستند. ابرها به دلیل متحرک بودن،
       نواحی نامناسبی برای تعیین نقاط کنترل به شمار می‌روند. Cpfind می‌تواند از
       همان الگوریتم celeste_standalone برای ماسک کردن نواحی حاوی ابر استفاده
       کند (این کار صرفاً به صورت داخلی در مرحله یافتن نقاط کلیدی انجام می‌شود و
       کانال آلفای تصویر شما را تغییر نمی‌دهد. در صورت تمایل به ایجاد تصویر
       ماسک، از celeste_standalone استفاده کنید). برای اجرای cpfind به همراه
       celeste از دستور زیر استفاده کنید:

          cpfind --celeste -o output.pto input.pto

       استفاده از cpfind با celeste داخلی نسبت به اجرای ترتیبی cpfind و
       celeste_standalone ارجحیت دارد. هنگام اجرای cpfind با celeste، نواحی
       ابری که معمولاً نقاط کلیدی با معیار کیفیت بالا دارند نادیده گرفته شده و
       در عوض نواحی بدون ابر به کار گرفته می‌شوند. در مقابل، هنگام اجرای cpfind
       بدون celeste، نقاط کلیدی روی ابرها نیز شناسایی می‌شوند و در صورت اجرای
       بعدی celeste_standalone، این نقاط کنترل حذف خواهند شد که در بدترین حالت
       ممکن است تمام نقاط کنترل یک جفت تصویر حذف شوند.

       بنابراین اجرای cpfind همراه با celeste منجر به "کیفیت بهتر نقاط کنترل"
       در پانوراماهای فضای باز (مانند پانوراماهای ابری) می‌شود. اجرای cpfind با
       celeste زمان بیشتری نسبت به اجرای cpfind به تنهایی می‌برد؛ از این رو
       برای پانوراماهای فضای بسته نیازی به تعیین این گزینه نیست (به دلیل زمان
       محاسباتی طولانی‌تر).

       مرحله celeste را می‌توان با پارامترهای --celesteRadius و
       --celesteThreshold به‌دقت تنظیم کرد.

   راهبرد تطبیق (Matching strategy)
       همه جفت‌ها (All pairs)

       این راهبرد پیش‌فرض تطبیق است. در این حالت، تمام جفت‌های تصویری با یکدیگر
       تطبیق داده می‌شوند. برای مثال اگر پروژه شامل ۵ تصویر باشد، cpfind این
       جفت‌ها را بررسی می‌کند: 0-1، 0-2، 0-3، 0-4، 1-2، 1-3، 1-4، 2-3، 2-4 و
       3-4.

       این راهبرد برای تمام روش‌های عکس‌برداری (تک‌ردیفه، چندردیفه، نامنظم) کار
       می‌کند و (تقریباً) تمامی جفت‌های متصل را می‌یابد؛ اما برای پروژه‌های با
       تصاویر زیاد از نظر محاسباتی سنگین است، زیرا جفت‌های تصویری بسیاری را که
       به یکدیگر متصل نیستند نیز بررسی می‌کند.

       تطبیق خطی (Linear match)

       این راهبرد تطبیق بهترین کارایی را برای پانوراماهای تک‌ردیفه دارد:

          cpfind --linearmatch -o output.pto input.pto

       این گزینه تنها جفت‌های مجاور را بررسی می‌کند؛ به عنوان مثال در پروژه ۵
       تصویری، جفت‌های 0-1، 1-2، 2-3 و 3-4 تطبیق داده می‌شوند. فاصله تطبیق را
       می‌توان با سوییچ --linearmatchlen افزایش داد. به عنوان مثال با
       --linearmatchlen 2 ابزار cpfind هر تصویر را با تصویر بعدی و تصویر پس از
       آن تطبیق می‌دهد که در مثال ما شامل 0-1، 0-2، 1-2، 1-3، 2-3، 2-4 و 3-4
       خواهد بود.

       تطبیق چندردیفه (Multirow matching)

       این یک راهبرد تطبیق بهینه‌سازی‌شده برای پانوراماهای تک‌ردیفه و چندردیفه
       است:

          cpfind --multirow -o output.pto input.pto

       الگوریتم آن همان الگوریتم توصیف‌شده برای پانوراماهای چندردیفه است. با
       ادغام این الگوریتم در cpfind، سرعت آن به دلیل بهره‌گیری از چندین هسته
       پردازنده‌های مدرن و عدم ذخیره موقت نقاط کلیدی روی دیسک (که زمان‌بر است)
       بسیار بیشتر شده است. اگر می‌خواهید از این تطبیق چندردیفه در محیط hugin
       استفاده کنید، نوع آشکارساز نقطه کنترل را روی All images at once قرار
       دهید.

       ذخیره موقت نقاط کلیدی روی دیسک (Keypoints caching to disc)

       محاسبه نقاط کلیدی زمان‌بر است؛ بنابراین cpfind این امکان را فراهم می‌کند
       که نقاط کلیدی در یک فایل ذخیره شده و بعداً مجدداً استفاده شوند. با گزینه
       --kall نقاط کلیدی تمام تصاویر پروژه روی دیسک ذخیره می‌شوند. اگر فقط نقاط
       کلیدی یک تصویر خاص را می‌خواهید، از پارامتر -k به همراه شماره تصویر
       استفاده کنید:

          cpfind --kall input.pto
          cpfind -k 0 -k 1 input.pto

       فایل‌های نقاط کلیدی به‌طور پیش‌فرض در همان دایرکتوری تصاویر و با پسوند
       .key ذخیره می‌شوند. در این حالت هیچ تطبیقی میان تصاویر رخ نمی‌دهد و
       بنابراین نیازی به تعیین فایل پروژه خروجی نیست. اگر cpfind فایل‌های کلید
       مربوط به یک تصویر در پروژه را پیدا کند، به‌طور خودکار از آن‌ها استفاده
       کرده و توصیف‌گر ویژگی‌ها را مجدداً روی آن تصویر اجرا نمی‌کند. برای ذخیره
       آن‌ها در دایرکتوری دیگر، از سوییچ --keypath استفاده کنید.

       این فرآیند را می‌توان با سوییچ --cache نیز خودکار کرد:

          cpfind --cache -o output.pto input.pto

       در این حالت برنامه تلاش می‌کند فایل‌های موجود نقاط کلیدی را بارگذاری کند.
       برای تصاویری که فاقد فایل نقطه کلیدی هستند، نقاط کلیدی شناسایی شده و در
       فایل ذخیره می‌شوند. سپس تمام نقاط کلیدی بارگذاری‌شده و تازه‌یافته‌شده را
       تطبیق داده و فایل پروژه خروجی را می‌نویسد.

       اگر دیگر به فایل‌های کلید نیازی ندارید، می‌توان آن‌ها را به‌طور خودکار با
       دستور زیر حذف کرد:

          cpfind --clean input.pto

گزینه‌های پیشرفته (EXTENDED OPTIONS)
   توصیف ویژگی‌ها (Feature description)
       به منظور افزایش سرعت، cpfind از تصاویری که به نصف عرض و ارتفاع خود
       مقیاس‌بندی شده‌اند برای یافتن نقاط کلیدی استفاده می‌کند. با سوییچ
       --fullscale برنامه روی تصاویر با مقیاس کامل کار می‌کند. این کار زمان
       بیشتری می‌برد اما می‌تواند نقاط کنترل "بهتر" و/یا بیشتری ارائه دهد.

       مرحله توصیف ویژگی را می‌توان با پارامترهای زیر به‌دقت تنظیم کرد:

       --sieve1width <int>
           غربال ۱: تعداد بخش‌ها (باکت‌ها) در عرض (پیش‌فرض: ۱۰)

       --sieve1height <int>
           غربال ۱: تعداد بخش‌ها (باکت‌ها) در ارتفاع (پیش‌فرض: ۱۰)

       --sieve1size <int>
           غربال ۱: حداکثر نقاط در هر بخش (پیش‌فرض: ۱۰۰)

       --kdtreesteps <int>
           درخت کی‌دی (KDTree): گام‌های جستجو (پیش‌فرض: ۲۰۰)

       --kdtreeseconddist <double>

       درخت کی‌دی (KDTree): فاصله دومین تطبیق (پیش‌فرض: ۰٫۲۵)

       ابزار Cpfind حداکثر sieve1width * sieve1height * sieve1size نقطه کلیدی
       را برای هر تصویر ذخیره می‌کند. اگر همپوشانی کمی دارید (مثلاً در
       پانوراماهای ۳۶۰ درجه ثبت‌شده با لنز چشم‌ماهی)، افزایش sieve1size نتایج
       بهتری به همراه خواهد داشت. همچنین می‌توانید sieve1width و/یا
       sieve1height را افزایش دهید.

   تطبیق ویژگی‌ها (Feature matching)
       تنظیم دقیق مرحله تطبیق با پارامترهای زیر امکان‌پذیر است:

       --ransaciter <int>
           رنسک (Ransac): تعداد تکرارها (پیش‌فرض: ۱۰۰۰)

       --ransacdist <int>
           رنسک (Ransac): آستانه فاصله برآورد هموگرافی بر حسب پیکسل (پیش‌فرض:
           ۲۵)

       --ransacmode (auto, hom, rpy, rpyv, rpyb)
           انتخاب مدل مورد استفاده در مرحله رنسک (Ransac).

           hom: فرض وجود هموگرافی. تنها برای نماهای غیرعریض قابل استفاده است.
           از کد اصلی panomatic استفاده می‌کند. همچنین انعطاف‌پذیری بیش از حد
           نیاز دارد و می‌تواند تطبیق‌های نادرست ایجاد کند، به‌ویژه اگر بیشتر
           تطبیق‌ها روی یک خط منفرد قرار گرفته باشند.

           rpy: تراز کردن تصاویر با استفاده از دوران، شیب و انحراف (Roll,
           Pitch, Yaw). این حالت نیازمند برآورد مناسبی از میدان دید افقی (و
           اعوجاج، برای تصاویر با اعوجاج شدید) است. در صورت استفاده از لنز
           کالیبره‌شده یا خوانده شدن موفق HFOV از داده‌های EXIF، این حالت ترجیح
           داده می‌شود.

           rpyv: تراز کردن جفت با بهینه‌سازی دوران، شیب، انحراف و میدان دید.
           باید بدون آگاهی قبلی از میدان دید کار کند، اما به دلیل تابع خطای
           مورد استفاده در بهینه‌ساز panotools ممکن است بیشتر با شکست مواجه
           شود؛ این تابع تمایل دارد میدان دید را به صفر کاهش دهد.

           rpyvb: تراز کردن جفت با بهینه‌سازی دوران، شیب، انحراف، میدان دید و
           پارامتر اعوجاج "b". احتمالاً بسیار شکننده است و صرفاً برای آزمایش
           پیاده‌سازی شده است.

           auto: استفاده از هموگرافی برای تصاویر با hfov کمتر از ۶۵ درجه و rpy
           برای سایر موارد.

       --minmatches <int>
           حداقل تعداد تطبیق‌ها (پیش‌فرض: ۴)

       --sieve2width <int>
           غربال ۲: تعداد بخش‌ها در عرض (پیش‌فرض: ۵)

       --sieve2height <int>
           غربال ۲: تعداد بخش‌ها در ارتفاع (پیش‌فرض: ۵)

       --sieve2size <int>
           غربال ۲: حداکثر نقاط در هر بخش (پیش‌فرض: ۲)

           ابزار Cpfind بین minmatches تا sieve2width * sieve2height *
           sieve2size نقطه کنترل بین یک جفت تصویر ایجاد می‌کند (تنظیمات پیش‌فرض
           بین ۴ تا ۵۰ [=۲*۵*۵] نقطه کنترل برای هر جفت تصویر است). اگر تعداد
           نقاط کنترل یافت‌شده برای یک جفت تصویر کمتر از minmatches باشد، این
           نقاط نادیده گرفته شده و آن جفت تصویر به عنوان غیرمتصل تلقی می‌شود.
           برای همپوشانی‌های باریک می‌توانید minmatches را کاهش دهید، اما این
           کار خطر ایجاد نقاط کنترل اشتباه را افزایش می‌دهد.

گزینه‌ها (OPTIONS)
       --celesteRadius <int>
           شعاع برای celeste (پیش‌فرض: ۲۰)

       --celesteThreshold <double>
           آستانه برای celeste (پیش‌فرض: ۰٫۵)

       --celeste
           اجرای تشخیص آسمان celeste پس از بارگذاری تصاویر؛ این گزینه تمام
           ویژگی‌های مرتبط با «ابرها» را نادیده می‌گیرد.

       -p <string, --keypath <string>
           مسیر ذخیره موقت فایل‌های کلید

       --clean
           پاک‌سازی فایل‌های کلید ذخیره‌شده

       -c, --cache
           ذخیره موقت نقاط کلیدی در فایل خارجی

       --kall
           نوشتن فایل‌های کلید برای تمامی تصاویر

       -k <int>, --writekeyfile <int>
           نوشتن یک فایل کلید برای این شماره تصویر (قابلیت تکرار چندباره دارد)

       -o <string>, --output <string>
           فایل خروجی، الزامی

       -n <int>, --ncores <int>
           تعداد پردازنده/هسته‌ها (پیش‌فرض: تشخیص خودکار)

       -t, --test
           فعال‌سازی حالت آزمایشی

       --fullscale
           استفاده از مقیاس کامل تصویر برای تشخیص نقاط کلیدی (پیش‌فرض: غیرفعال)

       --sieve1width <int>
           غربال ۱: تعداد بخش‌ها در عرض (پیش‌فرض: ۱۰)

       --sieve1height <int>
           غربال ۱: تعداد بخش‌ها در ارتفاع (پیش‌فرض: ۱۰)

       --sieve1size <int>
           غربال ۱: حداکثر نقاط در هر بخش (پیش‌فرض: ۱۰۰)

       --kdtreesteps <int>
           درخت کی‌دی (KDTree): گام‌های جستجو (پیش‌فرض: ۲۰۰)

       --kdtreeseconddist <double>
           درخت کی‌دی (KDTree): فاصله دومین تطبیق (پیش‌فرض: ۰٫۱۵)

       --multirow
           فعال‌سازی تطبیق مکاشفه‌ای چندردیفه (پیش‌فرض: غیرفعال)

       --linearmatch
           فعال‌سازی تطبیق خطی تصاویر (پیش‌فرض: تمام جفت‌ها)

       --linearmatchlen <int>
           تعداد تصاویر برای تطبیق در تطبیق خطی (پیش‌فرض: ۱)

       --minmatches <int>
           حداقل تعداد تطبیق‌ها (پیش‌فرض: ۴)

       --ransaciter <int>
           رنسک (Ransac): تعداد تکرارها (پیش‌فرض: ۱۰۰۰)

       --ransacdist <int>
           رنسک (Ransac): آستانه فاصله برآورد هموگرافی بر حسب پیکسل (پیش‌فرض:
           ۲۵)

       --sieve2width <int>
           غربال ۲: تعداد بخش‌ها در عرض (پیش‌فرض: ۵)

       --sieve2height <int>
           غربال ۲: تعداد بخش‌ها در ارتفاع (پیش‌فرض: ۵)

       --sieve2size <int>
           غربال ۲: حداکثر نقاط در هر بخش (پیش‌فرض: ۲)

       --, --ignore_rest
           نادیده گرفتن باقی آرگومان‌های برچسب‌دار پس از این فلگ.

       --version
           نمایش اطلاعات نسخه و خروج.

       -h, --help
           نمایش راهنمای استفاده و خروج.

نویسندگان (AUTHORS)
       Anael Orlinski, Pablo d'Angelo, Antoine Deleforge, Thomas Modes

"Version: 2025.0.1"               2026-01-05                       CPFIND("1")