GPSCORRELATE(1) gpscorrelate 2.3 GPSCORRELATE(1)

gpscorrelate - تطبیق تصاویر دیجیتال با داده‌های GPS و پر کردن فیلدهای EXIF

gpscorrelate [{-g file.gpx} | {[-l | --latlong latitude,longitude[,elevation] ]}] [-z | --timeadd +/-HH[:MM]] [--no-photo-tz] [-O | --photooffset seconds] [-i | --no-interpolation] [-v | --verbose] [-d | --datum datum] [-n | --no-write] [-R | --replace] [-m | --max-dist time] [-t | --ignore-tracksegs] [--heading] [-B | --max-heading degrees] [-b | --direction degrees] [-M | --no-mtime] [--degmins] image.jpg...

gpscorrelate {-s | --show | -o | --machine} image.jpg...

gpscorrelate {-x | --show-gpx} [-z | --timeadd +/-HH[:MM]] [--no-photo-tz] [-O | --photooffset seconds] image.jpg...

gpscorrelate {-r | --remove} [-M | --no-mtime] image.jpg...

gpscorrelate {-f | --fix-datestamps} {-z | --timeadd +/-HH[:MM]} image.jpg...

gpscorrelate -V | --version | -h | --help

این صفحه راهنما دستور gpscorrelate را مستند می‌کند. مستندات گسترده‌تری در قالب HTML موجود است؛ به انتهای این راهنما مراجعه فرمایید.

دستور gpscorrelate برنامه‌ای است که روی تصاویر دیجیتال با فرمت JPEG عمل می‌کند و فیلدهای EXIF (قالب فایل تصویری قابل تعویض) مربوط به اطلاعات سامانه موقعیت‌یاب جهانی (GPS) را تکمیل می‌نماید. منبع داده‌های GPS یک فایل با قالب GPX (فرمت تبادل GPS) است که اطلاعات مکان را بر پایه XML ذخیره می‌کند. عمل پر کردن این فیلدها با عنوان تطبیق (correlation) شناخته می‌شود.

اگر داده‌های GPS در لحظه دقیق ثبت عکس (با دقت ۱ ثانیه) موجود باشند، به صورت دست‌نخورده در فیلدهای EXIF ذخیره می‌شوند. در غیر این صورت، می‌توان از درونیابی خطی (linear interpolation) داده‌های GPS ثبت‌شده در لحظات قبل و بعد از عکس‌برداری استفاده کرد. اگر تصویر دارای وضوح زمانی کسری از ثانیه باشد، برای تخمین دقیق‌تر موقعیت بین دو نقطه به کار گرفته می‌شود. درونیابی خطی هنگامی که فاصله‌ها نزدیک باشد نتایج بسیار خوبی می‌دهد؛ اما اگر فاصله‌شان چندین کیلومتر باشد (مانند مسیر پرواز یک هواپیما با فواصل زمانی طولانی)، در مقایسه با مسیر دایره بزرگ (great circle) که هواپیماها معمولاً پرواز می‌کنند مقداری خطا پدید خواهد آمد. معیاری از دقت تقریبی خوانش مکان GPS (بر پایه تعداد ارقام اعشار ثبت‌شده در نقطه مسیر) از طریق مخرج فیلدهای مقادیر گویا در تصویر ذخیره و حفظ می‌شود. همچنین در صورت وجود اطلاعات HDOP ماهواره‌ها برای تطبیق دقیق نقطه‌ای، برچسب GPSDOP نیز نوشته می‌شود که برآوردی مطمئن‌تر از دقت مکان ارائه می‌دهد.

الگوریتم درونیابی فرض می‌کند که مقادیر زمانی در فایل‌های GPX اکیداً صعودی هستند، که در حالت عادی نیز چنین است. اگر فایلی با این فرض مغایرت داشته باشد، پیام Warning: track points are not ordered by time به همراه نخستین مقدار زمانی نامنظم در خروجی خطای استاندارد (stderr) نوشته می‌شود. هر مقدار مکانی ثبت‌شده در تصاویر با چنین فایلی ممکن است دقیق‌ترین مختصات ممکن نباشد (اگر عکس‌ها در حوالی زمان این ناهمخوانی زمانی گرفته شده باشند). در صورتی که زمان میان بخش‌های مسیر (track segments) به عقب بازگردد هشداری داده نمی‌شود؛ این موضوع تنها زمانی بر تطبیق اثر دارد که از گزینه --ignore-tracksegs استفاده شود. گزینه --max-dist می‌تواند برای تعیین حد مجاز شکاف زمانی استفاده شود تا در صورت بروز این مشکل، اثرات منفی آن مهار گردد.

این برنامه‌ها از ساختار معمول خط فرمان GNU پیروی می‌کنند که در آن گزینه‌های طولانی با دو خط تیره (`-') آغاز می‌شوند. خلاصه‌ای از گزینه‌ها در ادامه آمده است:

-g, --gps file.gpx

تطبیق تصاویر با استفاده از فایل GPX مشخص‌شده که حاوی نقاط مسیر GPS است. این گزینه می‌تواند چندین بار برای تعیین چندین فایل GPX داده شود. برای هر عکسی که تطبیق داده می‌شود، اولین فایلی که حاوی مسیری پوشش‌دهنده زمان ثبت عکس باشد استفاده خواهد شد. تمام بخش‌های <trk> در هر فایل به کار گرفته می‌شوند.

-l, --latlong latitude,longitude[,elevation]

تعیین یک مختصات جغرافیایی مشخص برای تمام عکس‌ها به جای تطبیق در امتداد یک مسیر در فایل GPX. ساختار باید به شکل کلی latitude,longitude,elevation باشد که در آن عرض جغرافیایی (latitude) و طول جغرافیایی (longitude) باید هر کدام به صورت اعشاری مانند -123.45678 یا بر حسب درجه/دقیقه/ثانیه مانند -123°45'67.8" یا -123d45m67s باشند. تعیین ارتفاع (elevation) اختیاری است. هر جزء می‌تواند با کاما، فاصله یا تب جدا شود.

توجه داشته باشید که این گزینه یک محدودیت شناخته‌شده دارد و در محلی‌سازی‌هایی (locales) که از کاراکتری جز "." برای ممیز استفاده می‌کنند، نماد اعشار محلی را در نظر نمی‌گیرد.

-s, --show

تنها نمایش داده‌های GPS موجود در برچسب‌های EXIF تصویر داده‌شده به جای تطبیق آن‌ها. زمان نمایش‌داده‌شده مستقیماً و بدون تغییر از تصویر خوانده می‌شود.

-x, --show-gpx

تنها نمایش داده‌های GPS تصاویر داده‌شده در قالب GPX. توجه داشته باشید که نقاط به ترتیبی که تصاویر در خط فرمان قرار گرفته‌اند نوشته می‌شوند، بنابراین حتماً آن‌ها را به ترتیب زمان عکس‌برداری وارد کنید. گزینه‌های -z/--timeadd و -O/--photooffset دقیقاً مانند فرآیند تطبیق برای تعیین منطقه زمانی صحیح تصاویر رعایت می‌شوند. تصاویری که قابل خواندن نیستند یا برچسب GPS ندارند نادیده گرفته می‌شوند. اگر زمان عکس‌های داده‌شده در خط فرمان اکیداً صعودی نباشد، پیام Warning: image files are not ordered by time. در stderr نوشته می‌شود.

-o, --machine

تنها نمایش داده‌های GPS تصاویر داده‌شده در قالب ماشین‌خوان CSV. زمان نشان‌داده‌شده مستقیماً و بدون تغییر از تصویر استخراج می‌شود. تصاویر بدون برچسب GPS نادیده گرفته می‌شوند. فیلدهای خروجی عبارتند از: نام فایل، تاریخ و زمان، عرض جغرافیایی، طول جغرافیایی و ارتفاع؛ که مقدار اول نام فایل ورودی، مقدار دوم برچسب زمانی و سه مقدار آخر اعدادی ممیز شناور همراه با علامت مثبت یا منفی اختیاری هستند.

-r, --remove

حذف تمامی داده‌های GPS EXIF از تصاویر مشخص‌شده. توجه داشته باشید که این گزینه تنها برچسب‌های GPSای را حذف می‌کند که برنامه توانایی افزودن آن‌ها را دارد؛ بنابراین همه برچسب‌های ممکن GPS EXIF را پاک نمی‌کند. سایر برچسب‌ها دست‌نخورده باقی می‌مانند.

-z, --timeadd +/-HH[:MM]

زمانی که باید به نقاط GPS اضافه شود تا با برچسب‌های زمانی عکس‌ها همخوانی پیدا کند. برچسب‌های زمانی GPS به وقت UTC هستند؛ در حالی که زمان تصاویر معمولاً به وقت محلی ذخیره می‌شود. منطقه زمانی استفاده‌شده هنگام ثبت عکس‌ها را وارد کنید؛ مثلاً +8 برای پرث در استرالیای غربی یا -2:30 برای سنت جان در نیوفاندلند. این مقدار به صورت پیش‌فرض برابر با منطقه زمانی تعبیه‌شده در عکس است، یا اگر موجود نباشد (یا هنگامی که --no-photo-tz داده شده باشد)، اختلاف UTC منطقه زمانی محلی در هنگام پردازش نخستین تصویر خواهد بود (نسخه‌های پیش از ۱.۷ به صورت پیش‌فرض 00:00 بودند).

--no-photo-tz

نادیده گرفتن هرگونه برچسب EXIF از نوع OffsetTimeOriginal در عکس‌ها که منطقه زمانی عکس‌برداری را تعیین می‌کند. اگر این برچسب نادرست باشد، مثلاً کاربر هنگام سفر تنظیم دستی منطقه زمانی دوربین را فراموش کرده باشد، این گزینه مانع استفاده از آن می‌شود. با این گزینه، gpscorrelate به تشخیص خودکار منطقه زمانی بازمی‌گردد یا از مقدار تعیین‌شده به صورت دستی (در صورت استفاده از --timeadd) بهره می‌گیرد.

-O, --photooffset seconds

مدت زمان به ثانیه (مقادیر اعشاری مجاز هستند) که باید به برچسب زمانی عکس افزوده شود تا با زمان GPS تطبیق یابد. برای تعیین میزان ثانیه مورد نیاز، کافی است از دستگاه GPS خود در حالی که زمان جاری را نشان می‌دهد عکسی بگیرید و آن را با برچسب زمانی فایل عکس مقایسه نمایید. برچسب‌های زمانی EXIF در فایل تصویر بر اساس این مقدار تغییری نمی‌کنند.

-i, --no-interpolation

غیرفعال کردن درونیابی خطی میان نقاط. با این فلگ، نزدیک‌ترین نقطه دقیق (در محدوده --max-dist) استفاده می‌شود. بدون این فلگ، عکس‌های گرفته‌شده میان زمان دو مختصات ثبت‌شده GPS بر پایه درونیابی خطی بین آن دو نقطه تطبیق می‌یابند.

-v, --verbose

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

-d, --datum datum

تعیین مبنای ژئودتیک (datum) اندازه‌گیری GPS. اگر تنظیم نشود، از WGS-84 استفاده می‌شود (TOKYO گزینه محتمل دیگر است). با این حال، فرمت GPX نباید داده‌ای جز WGS-84 ذخیره کند، بنابراین این گزینه معمولاً فقط همراه با گزینه --latlong مورد نیاز خواهد بود.

-n, --no-write

عدم ذخیره داده‌های تطبیق‌یافته EXIF در فایل تصویر. در کنار گزینه --verbose برای بررسی رویدادهایی که طی تطبیق رخ خواهد داد کاربرد دارد.

-R, --replace

بازنویسی برچسب‌های موجود GPS در فایل. بدون این گزینه، هر فایلی که از پیش دارای برچسب‌های GPS باشد نادیده گرفته خواهد شد.

-m, --max-dist time

حداکثر زمان به ثانیه نسبت به زمان ثبت عکس که یک نقطه ثبت‌شده GPS می‌تواند داشته باشد و همچنان برای تطبیق به کار رود. پیش‌فرض این گزینه 0 است که به معنای غیرفعال بودن این بررسی می‌باشد. کافی است یکی از دو نقطه در این بازه باشد تا تطبیق صورت پذیرد.

اگر دید مستقیم به تعداد ماهواره‌های لازم در زمان ثبت مسیر قطع شود، ممکن است شکاف‌هایی در داده‌های فایل GPX رخ دهد. اگر دقت موقعیت ثبت‌شده اهمیت حیاتی دارد و ترجیح می‌دهید در صورتی که مختصات موجود GPS بیش از حد متعلق به گذشته یا آینده است هیچ مکانی برای عکس تطبیق نیابد، این گزینه را روی مقداری غیرصفر تنظیم کنید.

این گزینه همچنین از ثبت جهت حرکت و زاویه دوربین در همین شرایط جلوگیری می‌کند (توضیحات گزینه --max-heading را برای کاربرد آن ببینید).

-t, --ignore-tracksegs

درونیابی میان بخش‌های مختلف مسیر (track segments). معمولاً بخش‌های مسیر نمایانگر جلسات ضبط جداگانه GPS هستند که فاصله میان آن‌ها نشان‌دهنده عدم ضبط توسط GPS است. از آنجا که درونیابی گزینه --max-dist را رعایت می‌کند، در صورت تنظیم هر دو گزینه، حتی بخش‌های دارای فاصله زمانی زیاد نیز بدون نگرانی قابل استفاده خواهند بود. بدون این فلگ، عکس‌های گرفته‌شده در فاصله زمانی میان دو بخش <trkseg> در فایل GPX تطبیق داده نمی‌شوند.

--heading

نوشتن برچسب EXIF مربوط به جهت حرکت در لحظه ثبت عکس. این امر تنها در صورتی ممکن است که جهت در برچسبی مناسب درون ورودی <trkpt> در فایل GPX ذخیره شده باشد. برچسب‌های پشتیبانی‌شده عبارتند از course (از GPX 1.0)، extensions/TrackPointExtension/course (یک Garmin® TrackPointExtension)، و extensions/compass (تولیدشده توسط OSMTracker).

برنامه gpscorrelate با تمامی این برچسب‌ها به عنوان جهت واقعی حرکت برخورد می‌کند؛ اما این برچسب‌ها استاندارد کاملاً مشخصی ندارند و ممکن است همیشه حامل داده‌های مورد انتظار نباشند. برای مثال، تلفن همراه ممکن است جهتی که دستگاه به سمت آن گرفته شده را ذخیره کند نه جهت جابجایی را، یا ممکن است جهت نسبت به شمال مغناطیسی باشد نه شمال واقعی. همچنین ممکن است دستگاه جهت را از روی سرعت پایین حرکت GPS تخمین بزند که دقیق نخواهد بود. با تکیه بر شناخت خود از نرم‌افزار ثبت‌کننده مسیر، میزان قابلیت اطمینان این برچسب‌ها را بسنجید.

اگر این گزینه با --latlong به جای --gps به کار رود، جهت ثابت 0 ثبت خواهد شد (این رفتار ممکن است در آینده تغییر کند).

-B, --max-heading degrees

عدم درج برچسب‌های --heading و --direction برای تصاویری که در آن‌ها جهت حرکت بین نقاط GPX مورد استفاده، بیش از تعداد درجات تعیین‌شده تغییر کرده باشد. این امر مانع از ثبت مقادیری می‌شود که به دلیل عکس‌برداری در زمان پیچیدن تند احتمالاً نادرست هستند. این قابلیت به صورت پیش‌فرض غیرفعال است.

این گزینه مانع از ثبت جهت یا زاویه نادرست در مواردی که نقاط GPS با فاصله‌ای بیشتر از زمان لازم برای دور زدن کامل وسیله نقلیه ثبت شده‌اند نخواهد شد. برای مثال، اگر خودرو برای دور زدن کامل به ۸ ثانیه نیاز داشته باشد اما برچسب‌های GPS هر ۱۰ ثانیه ثبت شوند، دو نقطه ابتدا و انتهای دور زدن ممکن است جهت‌هایی بسیار نزدیک داشته باشند (در محدوده --max-heading)؛ اما عکسی که در میانه چرخش و ۴ ثانیه پس از نقطه اول گرفته شده، زاویه‌ای درونیابی‌شده خواهد داشت که حدود ۱۸۰ درجه با واقعیت اختلاف دارد. با تنظیم گزینه --max-dist روی مقداری بسیار کمتر از مدت چرخش (مانند ۴ در این مثال)، از ثبت چنین مقادیر نادرستی جلوگیری کنید.

-b, --direction degrees

نوشتن یک برچسب EXIF که جهت اشاره دوربین را در زمان ثبت تصویر نشان می‌دهد. آرگومان degrees اختلاف زاویه میان جهت حرکت (مقداری که در صورت تعیین --heading نوشته می‌شد) و راستای دوربین را تعیین می‌کند. برای مثال، اگر دوربین به سمت پنجره سمت راست خودرو اشاره داشته باشد، این مقدار به صورت --direction 90 تنظیم می‌شود. اگر گزینه --heading نیز مشخص شده باشد، این دو برچسب همواره به اندازه همین مقدار درجه با یکدیگر اختلاف خواهند داشت. اگر دقت برایتان مهم است، از گزینه‌های --max-heading و --max-dist استفاده کنید تا درج این برچسب‌ها به زمان‌هایی محدود شود که موقعیت مکانی تثبیت شده و پیچ تندی رخ نداده باشد. از آنجا که این گزینه برای تمام طول مسیر اعمال می‌شود، تنها زمانی مفید است که دوربین در طول سفر نسبت به خودرو در وضعیتی ثابت نصب شده باشد.

این گزینه می‌تواند همراه با --latlong نیز استفاده شود، که در این حالت آرگومان به صورت مستقیم به عنوان راستای دوربین بدون تغییر منظور می‌گردد.

-M, --no-mtime

عدم تغییر زمان آخرین اصلاح (mtime) فایل‌های ویرایش‌شده.

-f, --fix-datestamps

اصلاح برچسب‌های تاریخ نامعتبر GPS که با نگارش‌های قبل از 1.5.2 نرم‌افزار gpscorrelate نوشته شده‌اند، با جایگزینی آن‌ها با برچسب زمانی عکس. پیش از نگارش 1.5.2، دو باگ مقادیر اشتباهی در برچسب‌های GPSDateStamp و GPSTimeStamp درج می‌کردند. این گزینه تک‌تک فایل‌های ورودی را بررسی کرده و در صورت وجود مشکل، آن را تصحیح می‌کند. از این گزینه همراه با --no-write استفاده کنید تا از اعمال تغییرات جلوگیری شود (جهت بررسی وجود مشکل). این گزینه متضمن --no-mtime نیز می‌باشد. همچنین لازم است از گزینه --timeadd برای تعیین اختلاف زمان محلی با ساعت UTC برای تصاویر داده‌شده استفاده کنید.

--degmins

نوشتن موقعیت مکانی به فرمت DD MM.MM (به جای فرمت دقیق‌تر DD MM SS.SS) که در نسخه‌های پیش از 1.5.3 برنامه gpscorrelate پیش‌فرض بود. هیچ دلیل مناسبی برای استفاده از این گزینه وجود ندارد مگر آنکه نرم‌افزار قدیمی و معیوبی انتظار این سبک را داشته باشد.

-h, --help

تنها نمایش خلاصه‌ای از گزینه‌های موجود.

-V, --version

تنها چاپ شماره نگارش برنامه gpscorrelate و اطلاعات حق نشر.

تطبیق تمامی عکس‌های موجود در یک پوشه که در فصل تابستان در اروپای غربی گرفته شده‌اند (یعنی UTC-2):

gpscorrelate -g Test.gpx -z 2 *.jpg

تطبیق تمام عکس‌های یک پوشه ثبت‌شده در ایتالیا، همراه با تغییر خودکار به UTC-2 یا UTC-1 بر اساس ساعت تابستانی معتبر در زمان ثبت نخستین تصویر فهرست:

env TZ=Europe/Rome gpscorrelate -g Test.gpx *.jpg

تطبیق تمام عکس‌های یک پوشه از مسیری که در دو فایل GPX مجزا پخش شده و در منطقه زمانی فعلی رایانه گرفته شده‌اند؛ همراه با درونیابی میان قطعات و بین فایل‌ها در عین صرف‌نظر از عکس‌های با فاصله زیاد از نقطه ثبت‌شده، بدون تغییر برچسب زمانی فایل‌ها، و با نمایش جزئیات کامل فرآیند:

gpscorrelate -g track1.gpx -g track2.gpx -m 120 -t -M -v *.jpg

تطبیق عکس‌های گرفته‌شده با دوربین داشبورد، همراه با افزودن برچسب‌های جهت از فایل GPX:

gpscorrelate --heading --max-heading 90 --direction 0 -g Test.gpx *.jpg

تطبیق مجموعه‌ای از عکس‌های گرفته‌شده با دوربینی که مستقیماً به سمت شیشه سمت راست خودرو نشانه رفته است (۹۰ درجه زاویه نسبت به جلو)، با استفاده از فایل GPX دارای برچسب‌های جهت، صرف‌نظر از برچسب‌گذاری جهت در پیچ‌های تند و حذف تمام برچسب‌ها در صورت قطع سیگنال GPS برای بیش از ۶ ثانیه (جهت جلوگیری از ثبت مقادیر نادرست):

gpscorrelate -g car_trip.gpx --heading --max-heading 45 --direction 90 --max-dist 6 --ignore-tracksegs *.jpg

تطبیق عکسی ثبت‌شده با دوربینی با ساعت جلوتر (ساعت ۷۷.۵ ثانیه جلوتر از زمان GPS بوده است) و برچسب‌های منطقه زمانی اشتباه:

gpscorrelate -g Test.gpx -O -77.5 --no-photo-tz photo.jpg

نمایش برچسب‌های موجود GPS در یک عکس:

gpscorrelate --show photo.jpg

نمایش برچسب‌های موجود GPS در عکس و خروجی در قالب CSV:

gpscorrelate --show --machine photo.jpg

ایجاد یک مسیر GPX از مجموعه‌ای از عکس‌های گرفته‌شده در زمستان در بریتانیا که دارای برچسب GPS هستند (مانند عکس‌های گوشی)، جهت استفاده در تطبیق عکس‌های دوربینی دیگر در همان نزدیکی:

gpscorrelate --show-gpx -z 0 IMG*.JPG

حذف برچسب‌های GPS از عکس‌ها:

gpscorrelate --remove *.jpg

افزودن برچسب موقعیت GPS به عکسی ثبت‌شده رو به سمت جنوب‌شرقی در کلیسای اولم:

gpscorrelate -l 48.398620,9.991417,522 --direction 135 -z 2 ulm.jpg

دستور gpscorrelate در صورت موفقیت مقدار 0، در صورت بروز خطای عمده (مانند خطای خواندن یا نوشتن) مقدار 1 و در صورت خطای جزئی (مانند پوشش ندادن زمان تصویر توسط مسیر GPS داده‌شده) مقدار 2 را برمی‌گرداند.

gpsd(1), gpsbabel(1), gpxlogger(1), cgpxlogger(1).

مستندات کامل نرم‌افزار gpscorrelate در قالب HTML در مسیر زیر بر روی فایل‌سیستم در دسترس است: /usr/share/doc/gpscorrelate.

این صفحه راهنما در ابتدا توسط Stefano Zacchiroli <zack@debian.org> برای سیستم Debian(TM) نگاشته شد. سپس توسط Till Maas <opensource@till.name> و Dan Fandrich <dan@coneharvesters.com> گسترش یافت. حق تکثیر، توزیع و/یا تغییر این سند تحت شرایط مجوز عمومی همگانی گنو (GNU General Public License)، نسخه ۲ یا هر نسخه پس از آن منتشرشده توسط بنیاد نرم‌افزارهای آزاد مجاز است.

Stefano Zacchiroli

نویسنده اصلی.

حق نشر © 2006-2025 متعلق به Stefano Zacchiroli <zack@debian.org>، Till Maas، Dan Fandrich

13 Feb 2025 gpscorrelate 2.3