.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "CPFIND ""1"""
.TH CPFIND """1""" 2026-01-05 """Version: 2025.0.1""" HUGIN
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "نام (NAME)"
cpfind \- ابزار یافتن و تطبیق نقاط کنترل برای اتصال پانوراما
.SH "خلاصه دستور (SYNOPSIS)"
.IX Header "SYNOPSIS"
\&\fBcpfind\fR [\fIگزینه‌ها\fR] \-o \fIoutput_project\fR \fIproject.pto\fR
.PP
\&\fBcpfind\fR [\fIگزینه‌ها\fR] \-k i0 \-k i1 [...] \fIproject.pto\fR
.PP
\&\fBcpfind\fR [\fIگزینه‌ها\fR] \-\-kall \fIproject.pto\fR
.SH "توضیحات (DESCRIPTION)"
.IX Header "DESCRIPTION"
دستور
.B cpfind
یک آشکارساز نقاط کنترل (Control-point) برای Hugin است. این برنامه یک فایل پروژه را به عنوان ورودی دریافت کرده و در صورت موفقیت، یک فایل پروژه حاوی نقاط کنترل ایجاد می‌کند. عملکرد آن به وجود اطلاعات معقول و دقیق لنز در فایل پروژه ورودی وابسته است.
.PP
گام نخست، توصیف ویژگی‌ها است: در این گام، تصاویر فایل پروژه بارگذاری شده و نقاط کلیدی (Keypoints) جستجو می‌شوند. این نقاط نشان‌دهنده ویژگی‌های متمایز تصویر هستند.
.B cpfind
از یک توصیف‌گر گرادیان‌محور برای توصیف ویژگی‌های نقاط کلیدی استفاده می‌کند.
.PP
در گام دوم، یعنی تطبیق ویژگی‌ها، تمام نقاط کلیدی دو تصویر با یکدیگر تطبیق داده می‌شوند تا ویژگی‌های مشترک موجود در هر دو تصویر شناسایی شوند. در صورت موفقیت‌آمیز بودن این تطبیق، دو نقطه کلیدی از دو تصویر به یک نقطه کنترل تبدیل می‌شوند.
.SH "نحوه استفاده (USAGE)"
.IX Header "USAGE"
.SS "تصاویر خطی مستقیم و چشم‌ماهی (Rectilinear and fisheye images)"
.IX Subsection "Rectilinear and fisheye images"
ابزار Cpfind قادر به یافتن نقاط کنترل در تصاویر مستقیم (Rectilinear) و چشم‌ماهی (Fisheye) است. برای دستیابی به نقاط کنترل مناسب، تصاویری که میدان دید افقی بالایی دارند (مانند تصاویر فوق عریض مستقیم یا چشم‌ماهی) به یک فضای هم‌شکل (کانفورمال) تبدیل می‌شوند (cpfind از تصویربرداری استریوگرافیک استفاده می‌کند) و فرآیند تطبیق ویژگی‌ها در این فضا صورت می‌گیرد. پیش از ذخیره نقاط کنترل، مختصات مجدداً به فضای تصویر بازگردانده می‌شوند. این فرآیند به صورت خودکار و بر اساس اطلاعات لنز در فایل پروژه ورودی انجام می‌شود؛ بنابراین اطمینان حاصل کنید که فایل پروژه ورودی شامل اطلاعات معقولی درباره لنز مورد استفاده باشد.
.SS "استفاده از سلست (Using celeste)"
.IX Subsection "Using celeste"
پانوراماهای فضای باز اغلب حاوی ابر هستند. ابرها به دلیل متحرک بودن، نواحی نامناسبی برای تعیین نقاط کنترل به شمار می‌روند. Cpfind می‌تواند از همان الگوریتم celeste_standalone برای ماسک کردن نواحی حاوی ابر استفاده کند (این کار صرفاً به صورت داخلی در مرحله یافتن نقاط کلیدی انجام می‌شود و کانال آلفای تصویر شما را تغییر نمی‌دهد. در صورت تمایل به ایجاد تصویر ماسک، از celeste_standalone استفاده کنید). برای اجرای cpfind به همراه celeste از دستور زیر استفاده کنید:
.PP
.Vb 1
\&   cpfind \-\-celeste \-o output.pto input.pto
.Ve
.PP
استفاده از cpfind با celeste داخلی نسبت به اجرای ترتیبی cpfind و celeste_standalone ارجحیت دارد. هنگام اجرای cpfind با celeste، نواحی ابری که معمولاً نقاط کلیدی با معیار کیفیت بالا دارند نادیده گرفته شده و در عوض نواحی بدون ابر به کار گرفته می‌شوند. در مقابل، هنگام اجرای cpfind بدون celeste، نقاط کلیدی روی ابرها نیز شناسایی می‌شوند و در صورت اجرای بعدی celeste_standalone، این نقاط کنترل حذف خواهند شد که در بدترین حالت ممکن است تمام نقاط کنترل یک جفت تصویر حذف شوند.
.PP
بنابراین اجرای cpfind همراه با celeste منجر به "کیفیت بهتر نقاط کنترل" در پانوراماهای فضای باز (مانند پانوراماهای ابری) می‌شود. اجرای cpfind با celeste زمان بیشتری نسبت به اجرای cpfind به تنهایی می‌برد؛ از این رو برای پانوراماهای فضای بسته نیازی به تعیین این گزینه نیست (به دلیل زمان محاسباتی طولانی‌تر).
.PP
مرحله celeste را می‌توان با پارامترهای
.B \-\-celesteRadius
و
.B \-\-celesteThreshold
به‌دقت تنظیم کرد.
.SS "راهبرد تطبیق (Matching strategy)"
.IX Subsection "Matching strategy"
\fIهمه جفت‌ها (All pairs)\fR
.IX Subsection "All pairs"
.PP
این راهبرد پیش‌فرض تطبیق است. در این حالت، تمام جفت‌های تصویری با یکدیگر تطبیق داده می‌شوند. برای مثال اگر پروژه شامل ۵ تصویر باشد، cpfind این جفت‌ها را بررسی می‌کند: 0\-1، 0\-2، 0\-3، 0\-4، 1\-2، 1\-3، 1\-4، 2\-3، 2\-4 و 3\-4.
.PP
این راهبرد برای تمام روش‌های عکس‌برداری (تک‌ردیفه، چندردیفه، نامنظم) کار می‌کند و (تقریباً) تمامی جفت‌های متصل را می‌یابد؛ اما برای پروژه‌های با تصاویر زیاد از نظر محاسباتی سنگین است، زیرا جفت‌های تصویری بسیاری را که به یکدیگر متصل نیستند نیز بررسی می‌کند.
.PP
\fIتطبیق خطی (Linear match)\fR
.IX Subsection "Linear match"
.PP
این راهبرد تطبیق بهترین کارایی را برای پانوراماهای تک‌ردیفه دارد:
.PP
.Vb 1
\&   cpfind \-\-linearmatch \-o output.pto input.pto
.Ve
.PP
این گزینه تنها جفت‌های مجاور را بررسی می‌کند؛ به عنوان مثال در پروژه ۵ تصویری، جفت‌های 0\-1، 1\-2، 2\-3 و 3\-4 تطبیق داده می‌شوند. فاصله تطبیق را می‌توان با سوییچ
.B \-\-linearmatchlen
افزایش داد. به عنوان مثال با
.B \-\-linearmatchlen 2
ابزار cpfind هر تصویر را با تصویر بعدی و تصویر پس از آن تطبیق می‌دهد که در مثال ما شامل 0\-1، 0\-2، 1\-2، 1\-3، 2\-3، 2\-4 و 3\-4 خواهد بود.
.PP
\fIتطبیق چندردیفه (Multirow matching)\fR
.IX Subsection "Multirow matching"
.PP
این یک راهبرد تطبیق بهینه‌سازی‌شده برای پانوراماهای تک‌ردیفه و چندردیفه است:
.PP
.Vb 1
\&   cpfind \-\-multirow \-o output.pto input.pto
.Ve
.PP
الگوریتم آن همان الگوریتم توصیف‌شده برای پانوراماهای چندردیفه است. با ادغام این الگوریتم در cpfind، سرعت آن به دلیل بهره‌گیری از چندین هسته پردازنده‌های مدرن و عدم ذخیره موقت نقاط کلیدی روی دیسک (که زمان‌بر است) بسیار بیشتر شده است. اگر می‌خواهید از این تطبیق چندردیفه در محیط hugin استفاده کنید، نوع آشکارساز نقطه کنترل را روی All images at once قرار دهید.
.PP
\fIذخیره موقت نقاط کلیدی روی دیسک (Keypoints caching to disc)\fR
.IX Subsection "Keypoints caching to disc"
.PP
محاسبه نقاط کلیدی زمان‌بر است؛ بنابراین cpfind این امکان را فراهم می‌کند که نقاط کلیدی در یک فایل ذخیره شده و بعداً مجدداً استفاده شوند. با گزینه
.B \-\-kall
نقاط کلیدی تمام تصاویر پروژه روی دیسک ذخیره می‌شوند. اگر فقط نقاط کلیدی یک تصویر خاص را می‌خواهید، از پارامتر
.B \-k
به همراه شماره تصویر استفاده کنید:
.PP
.Vb 2
\&   cpfind \-\-kall input.pto
\&   cpfind \-k 0 \-k 1 input.pto
.Ve
.PP
فایل‌های نقاط کلیدی به‌طور پیش‌فرض در همان دایرکتوری تصاویر و با پسوند
.I .key
ذخیره می‌شوند. در این حالت هیچ تطبیقی میان تصاویر رخ نمی‌دهد و بنابراین نیازی به تعیین فایل پروژه خروجی نیست. اگر cpfind فایل‌های کلید مربوط به یک تصویر در پروژه را پیدا کند، به‌طور خودکار از آن‌ها استفاده کرده و توصیف‌گر ویژگی‌ها را مجدداً روی آن تصویر اجرا نمی‌کند. برای ذخیره آن‌ها در دایرکتوری دیگر، از سوییچ
.B \-\-keypath
استفاده کنید.
.PP
این فرآیند را می‌توان با سوییچ
.B \-\-cache
نیز خودکار کرد:
.PP
.Vb 1
\&   cpfind \-\-cache \-o output.pto input.pto
.Ve
.PP
در این حالت برنامه تلاش می‌کند فایل‌های موجود نقاط کلیدی را بارگذاری کند. برای تصاویری که فاقد فایل نقطه کلیدی هستند، نقاط کلیدی شناسایی شده و در فایل ذخیره می‌شوند. سپس تمام نقاط کلیدی بارگذاری‌شده و تازه‌یافته‌شده را تطبیق داده و فایل پروژه خروجی را می‌نویسد.
.PP
اگر دیگر به فایل‌های کلید نیازی ندارید، می‌توان آن‌ها را به‌طور خودکار با دستور زیر حذف کرد:
.PP
.Vb 1
\&   cpfind \-\-clean input.pto
.Ve
.SH "گزینه‌های پیشرفته (EXTENDED OPTIONS)"
.IX Header "EXTENDED OPTIONS"
.SS "توصیف ویژگی‌ها (Feature description)"
.IX Subsection "Feature description"
به منظور افزایش سرعت، cpfind از تصاویری که به نصف عرض و ارتفاع خود مقیاس‌بندی شده‌اند برای یافتن نقاط کلیدی استفاده می‌کند. با سوییچ
.B \-\-fullscale
برنامه روی تصاویر با مقیاس کامل کار می‌کند. این کار زمان بیشتری می‌برد اما می‌تواند نقاط کنترل "بهتر" و/یا بیشتری ارائه دهد.
.PP
مرحله توصیف ویژگی را می‌توان با پارامترهای زیر به‌دقت تنظیم کرد:
.IP "\fB\-\-sieve1width\fR <int>" 4
.IX Item "--sieve1width <int>"
غربال ۱: تعداد بخش‌ها (باکت‌ها) در عرض (پیش‌فرض: ۱۰)
.IP "\fB\-\-sieve1height\fR <int>" 4
.IX Item "--sieve1height <int>"
غربال ۱: تعداد بخش‌ها (باکت‌ها) در ارتفاع (پیش‌فرض: ۱۰)
.IP "\fB\-\-sieve1size\fR <int>" 4
.IX Item "--sieve1size <int>"
غربال ۱: حداکثر نقاط در هر بخش (پیش‌فرض: ۱۰۰)
.IP "\fB\-\-kdtreesteps\fR <int>" 4
.IX Item "--kdtreesteps <int>"
درخت کی‌دی (KDTree): گام‌های جستجو (پیش‌فرض: ۲۰۰)
.IP "\fB\-\-kdtreeseconddist\fR <double>" 4
.IX Item "--kdtreeseconddist <double>"
.PP
درخت کی‌دی (KDTree): فاصله دومین تطبیق (پیش‌فرض: ۰٫۲۵)
.PP
ابزار Cpfind حداکثر sieve1width * sieve1height * sieve1size نقطه کلیدی را برای هر تصویر ذخیره می‌کند. اگر همپوشانی کمی دارید (مثلاً در پانوراماهای ۳۶۰ درجه ثبت‌شده با لنز چشم‌ماهی)، افزایش sieve1size نتایج بهتری به همراه خواهد داشت. همچنین می‌توانید sieve1width و/یا sieve1height را افزایش دهید.
.SS "تطبیق ویژگی‌ها (Feature matching)"
.IX Subsection "Feature matching"
تنظیم دقیق مرحله تطبیق با پارامترهای زیر امکان‌پذیر است:
.IP "\fB\-\-ransaciter\fR <int>" 4
.IX Item "--ransaciter <int>"
رنسک (Ransac): تعداد تکرارها (پیش‌فرض: ۱۰۰۰)
.IP "\fB\-\-ransacdist\fR <int>" 4
.IX Item "--ransacdist <int>"
رنسک (Ransac): آستانه فاصله برآورد هموگرافی بر حسب پیکسل (پیش‌فرض: ۲۵)
.IP "\fB\-\-ransacmode\fR (auto, hom, rpy, rpyv, rpyb)" 4
.IX Item "--ransacmode (auto, hom, rpy, rpyv, rpyb)"
انتخاب مدل مورد استفاده در مرحله رنسک (Ransac).
.Sp
hom: فرض وجود هموگرافی. تنها برای نماهای غیرعریض قابل استفاده است. از کد اصلی panomatic استفاده می‌کند. همچنین انعطاف‌پذیری بیش از حد نیاز دارد و می‌تواند تطبیق‌های نادرست ایجاد کند، به‌ویژه اگر بیشتر تطبیق‌ها روی یک خط منفرد قرار گرفته باشند.
.Sp
rpy: تراز کردن تصاویر با استفاده از دوران، شیب و انحراف (Roll, Pitch, Yaw). این حالت نیازمند برآورد مناسبی از میدان دید افقی (و اعوجاج، برای تصاویر با اعوجاج شدید) است. در صورت استفاده از لنز کالیبره‌شده یا خوانده شدن موفق HFOV از داده‌های EXIF، این حالت ترجیح داده می‌شود.
.Sp
rpyv: تراز کردن جفت با بهینه‌سازی دوران، شیب، انحراف و میدان دید. باید بدون آگاهی قبلی از میدان دید کار کند، اما به دلیل تابع خطای مورد استفاده در بهینه‌ساز panotools ممکن است بیشتر با شکست مواجه شود؛ این تابع تمایل دارد میدان دید را به صفر کاهش دهد.
.Sp
rpyvb: تراز کردن جفت با بهینه‌سازی دوران، شیب، انحراف، میدان دید و پارامتر اعوجاج "b". احتمالاً بسیار شکننده است و صرفاً برای آزمایش پیاده‌سازی شده است.
.Sp
auto: استفاده از هموگرافی برای تصاویر با hfov کمتر از ۶۵ درجه و rpy برای سایر موارد.
.IP "\fB\-\-minmatches\fR <int>" 4
.IX Item "--minmatches <int>"
حداقل تعداد تطبیق‌ها (پیش‌فرض: ۴)
.IP "\fB\-\-sieve2width\fR <int>" 4
.IX Item "--sieve2width <int>"
غربال ۲: تعداد بخش‌ها در عرض (پیش‌فرض: ۵)
.IP "\fB\-\-sieve2height\fR <int>" 4
.IX Item "--sieve2height <int>"
غربال ۲: تعداد بخش‌ها در ارتفاع (پیش‌فرض: ۵)
.IP "\fB\-\-sieve2size\fR <int>" 4
.IX Item "--sieve2size <int>"
غربال ۲: حداکثر نقاط در هر بخش (پیش‌فرض: ۲)
.Sp
ابزار Cpfind بین minmatches تا sieve2width * sieve2height * sieve2size نقطه کنترل بین یک جفت تصویر ایجاد می‌کند (تنظیمات پیش‌فرض بین ۴ تا ۵۰ [=۲*۵*۵] نقطه کنترل برای هر جفت تصویر است). اگر تعداد نقاط کنترل یافت‌شده برای یک جفت تصویر کمتر از minmatches باشد، این نقاط نادیده گرفته شده و آن جفت تصویر به عنوان غیرمتصل تلقی می‌شود. برای همپوشانی‌های باریک می‌توانید minmatches را کاهش دهید، اما این کار خطر ایجاد نقاط کنترل اشتباه را افزایش می‌دهد.
.SH "گزینه‌ها (OPTIONS)"
.IX Header "OPTIONS"
.IP "\fB\-\-celesteRadius\fR <int>" 4
.IX Item "--celesteRadius <int>"
شعاع برای celeste (پیش‌فرض: ۲۰)
.IP "\fB\-\-celesteThreshold\fR <double>" 4
.IX Item "--celesteThreshold <double>"
آستانه برای celeste (پیش‌فرض: ۰٫۵)
.IP \fB\-\-celeste\fR 4
.IX Item "--celeste"
اجرای تشخیص آسمان celeste پس از بارگذاری تصاویر؛ این گزینه تمام ویژگی‌های مرتبط با «ابرها» را نادیده می‌گیرد.
.IP "\fB\-p <string\fR, \fB\-\-keypath\fR <string>" 4
.IX Item "-p <string, --keypath <string>"
مسیر ذخیره موقت فایل‌های کلید
.IP \fB\-\-clean\fR 4
.IX Item "--clean"
پاک‌سازی فایل‌های کلید ذخیره‌شده
.IP "\fB\-c\fR, \fB\-\-cache\fR" 4
.IX Item "-c, --cache"
ذخیره موقت نقاط کلیدی در فایل خارجی
.IP \fB\-\-kall\fR 4
.IX Item "--kall"
نوشتن فایل‌های کلید برای تمامی تصاویر
.IP "\fB\-k\fR <int>, \fB\-\-writekeyfile\fR <int>" 4
.IX Item "-k <int>, --writekeyfile <int>"
نوشتن یک فایل کلید برای این شماره تصویر (قابلیت تکرار چندباره دارد)
.IP "\fB\-o\fR <string>, \fB\-\-output\fR <string>" 4
.IX Item "-o <string>, --output <string>"
فایل خروجی، الزامی
.IP "\fB\-n\fR <int>, \fB\-\-ncores\fR <int>" 4
.IX Item "-n <int>, --ncores <int>"
تعداد پردازنده/هسته‌ها (پیش‌فرض: تشخیص خودکار)
.IP "\fB\-t\fR, \fB\-\-test\fR" 4
.IX Item "-t, --test"
فعال‌سازی حالت آزمایشی
.IP \fB\-\-fullscale\fR 4
.IX Item "--fullscale"
استفاده از مقیاس کامل تصویر برای تشخیص نقاط کلیدی (پیش‌فرض: غیرفعال)
.IP "\fB\-\-sieve1width\fR <int>" 4
.IX Item "--sieve1width <int>"
غربال ۱: تعداد بخش‌ها در عرض (پیش‌فرض: ۱۰)
.IP "\fB\-\-sieve1height\fR <int>" 4
.IX Item "--sieve1height <int>"
غربال ۱: تعداد بخش‌ها در ارتفاع (پیش‌فرض: ۱۰)
.IP "\fB\-\-sieve1size\fR <int>" 4
.IX Item "--sieve1size <int>"
غربال ۱: حداکثر نقاط در هر بخش (پیش‌فرض: ۱۰۰)
.IP "\fB\-\-kdtreesteps\fR <int>" 4
.IX Item "--kdtreesteps <int>"
درخت کی‌دی (KDTree): گام‌های جستجو (پیش‌فرض: ۲۰۰)
.IP "\fB\-\-kdtreeseconddist\fR <double>" 4
.IX Item "--kdtreeseconddist <double>"
درخت کی‌دی (KDTree): فاصله دومین تطبیق (پیش‌فرض: ۰٫۱۵)
.IP \fB\-\-multirow\fR 4
.IX Item "--multirow"
فعال‌سازی تطبیق مکاشفه‌ای چندردیفه (پیش‌فرض: غیرفعال)
.IP \fB\-\-linearmatch\fR 4
.IX Item "--linearmatch"
فعال‌سازی تطبیق خطی تصاویر (پیش‌فرض: تمام جفت‌ها)
.IP "\fB\-\-linearmatchlen\fR <int>" 4
.IX Item "--linearmatchlen <int>"
تعداد تصاویر برای تطبیق در تطبیق خطی (پیش‌فرض: ۱)
.IP "\fB\-\-minmatches\fR <int>" 4
.IX Item "--minmatches <int>"
حداقل تعداد تطبیق‌ها (پیش‌فرض: ۴)
.IP "\fB\-\-ransaciter\fR <int>" 4
.IX Item "--ransaciter <int>"
رنسک (Ransac): تعداد تکرارها (پیش‌فرض: ۱۰۰۰)
.IP "\fB\-\-ransacdist\fR <int>" 4
.IX Item "--ransacdist <int>"
رنسک (Ransac): آستانه فاصله برآورد هموگرافی بر حسب پیکسل (پیش‌فرض: ۲۵)
.IP "\fB\-\-sieve2width\fR <int>" 4
.IX Item "--sieve2width <int>"
غربال ۲: تعداد بخش‌ها در عرض (پیش‌فرض: ۵)
.IP "\fB\-\-sieve2height\fR <int>" 4
.IX Item "--sieve2height <int>"
غربال ۲: تعداد بخش‌ها در ارتفاع (پیش‌فرض: ۵)
.IP "\fB\-\-sieve2size\fR <int>" 4
.IX Item "--sieve2size <int>"
غربال ۲: حداکثر نقاط در هر بخش (پیش‌فرض: ۲)
.IP "\fB\-\-\fR, \fB\-\-ignore_rest\fR" 4
.IX Item "--, --ignore_rest"
نادیده گرفتن باقی آرگومان‌های برچسب‌دار پس از این فلگ.
.IP \fB\-\-version\fR 4
.IX Item "--version"
نمایش اطلاعات نسخه و خروج.
.IP "\fB\-h\fR, \fB\-\-help\fR" 4
.IX Item "-h, --help"
نمایش راهنمای استفاده و خروج.
.SH "نویسندگان (AUTHORS)"
.IX Header "AUTHORS"
Anael Orlinski, Pablo d\*(AqAngelo, Antoine Deleforge, Thomas Modes