GDALLOCATIONINFO(1)

GDAL

GDALLOCATIONINFO(1)

نام (NAME)

gdallocationinfo - ابزار پرس‌وجوی رستر.

خلاصه دستور (SYNOPSIS)

Usage: gdallocationinfo [--help] [--long-usage] [--help-general]
                        [-xml] [-lifonly] [-valonly] [-E] [-field_sep <sep>]
                        [-ignore_extra_input] [-b <band>]...
                        [-overview <overview_level>]
                        [-r nearest|bilinear|cubic|cubicspline]
                        [[-l_srs <srs_def>]|[-geoloc]|[-wgs84]]
                        [-oo <NAME>=<VALUE>]...
                        <srcfile> <x> <y>

توضیحات (DESCRIPTION)

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

نکته:

معادل در رابط خط فرمان جدید "gdal":

دستور gdal raster pixel-info را ببینید.

--help: نمایش این پیام راهنما و خروج.

--help-general: نمایش یک پیام کاربرد کوتاه برای گزینه‌های خط فرمان عمومی GDAL و خروج.

-xml: گزارش خروجی برای پردازش بعدی آسان، با فرمت XML قالب‌بندی می‌شود. (مثال ۲).

-lifonly: تنها خروجی، نام فایل‌های حاصل از درخواست LocationInfo در پایگاه داده خواهد بود (یعنی برای شناسایی فایل تحت تأثیر در VRT).

-valonly: تنها خروجی، مقادیر پیکسل برای پیکسل انتخاب‌شده در هر یک از باندهای انتخاب‌شده خواهد بود. به‌طور پیش‌فرض، مقدار هر باند در یک خط جداگانه ارائه می‌شود، مگر اینکه -field_sep مشخص شده باشد.

-b <band>: انتخاب یک باند برای پرس‌وجو. چندین باند را می‌توان فهرست کرد. به‌طور پیش‌فرض تمام باندها پرس‌وجو می‌شوند.

-r {nearest|bilinear|cubic|cubicspline}

در نسخه 3.10 اضافه شد.

انتخاب یک الگوریتم نمونه‌برداری. مقدار پیش‌فرض nearest است.

روش‌های موجود عبارتند از:

nearest نزدیک‌ترین همسایه را اعمال می‌کند.

bilinear هسته پیچش دوخطی (bilinear) را اعمال می‌کند.

cubic هسته پیچش مکعبی (cubic) را اعمال می‌کند.

cubicspline هسته پیچش B-Spline را اعمال می‌کند.

-overview <overview_level>: پرس‌وجوی نمای کلی (overview) شماره (overview_level) (سطح overview_level=1 نخستین نمای کلی است)، به جای باند اصلی. توجه داشته باشید که موقعیت x,y (اگر دستگاه مختصات pixel/line باشد) همچنان باید نسبت به باند اصلی ارائه شود.

-l_srs <srs_def>: دستگاه مختصات موقعیت ورودی x, y.

-geoloc: نشان می‌دهد نقاط ورودی x,y در دستگاه ارجاع مکانی تصویر هستند.

-wgs84: نشان می‌دهد نقاط ورودی x,y بر حسب طول و عرض جغرافیایی WGS84 هستند.

-oo <NAME>=<VALUE>: گزینه باز کردن مجموعه داده (مختص فرمت)

-ignore_extra_input: در نسخه 3.9 اضافه شد.
تنظیم این پرچم به منظور جلوگیری از الحاق محتوای غیرعددی اضافی در انتهای خطوط ورودی به خطوط خروجی در حالت -valonly (مستلزم تعریف -field_sep نیز می‌باشد)، یا به عنوان یک فیلد اختصاصی در حالت‌های پیش‌فرض یا -xml.

-E: در نسخه 3.9 اضافه شد.
فعال کردن حالت بازتاب (Echo)، که در آن مختصات ورودی به ابتدای خطوط خروجی در حالت -valonly افزوده می‌شوند.

-field_sep <sep>: در نسخه 3.9 اضافه شد.
تعریف جداکننده فیلد که در حالت -valonly برای جداسازی مقادیر مختلف به کار می‌رود. مقدار پیش‌فرض آن نویسه خط جدید است؛ بدین معنی که هنگام پرس‌وجوی یک رستر با چند باند، خروجی شامل یک مقدار در هر خط خواهد بود، که در صورت ارائه چندین نقطه ممکن است تشخیص این که کدام مقدار به کدام مجموعه نقاط ورودی x,y تعلق دارد را دشوار کند. تعریف جداکننده فیلد همچنین مورد نیاز است

<srcfile>: نام منبع داده رستر GDAL مبدأ.

<x>: موقعیت X پیکسل هدف. به‌طور پیش‌فرض دستگاه مختصات pixel/line است مگر این که -l_srs، -wgs84 یا -geoloc ارائه شده باشد.

<y>: موقعیت Y پیکسل هدف. به‌طور پیش‌فرض دستگاه مختصات pixel/line است مگر این که -l_srs، -wgs84 یا -geoloc ارائه شده باشد.

این ابزار به منظور ارائه اطلاعات متنوعی درباره یک پیکسل طراحی شده است. در حال حاضر موارد زیر را گزارش می‌دهد:

موقعیت مکانی پیکسل در فضای pixel/line (پیکسل/سطر).
نتیجه یک پرس‌وجوی فراداده‌ای LocationInfo روی منبع داده. این ویژگی برای فایل‌های VRT پیاده‌سازی شده است که فایل(های) مورد استفاده برای برآورده کردن درخواست‌ها برای آن پیکسل را گزارش می‌دهند، و همچنین توسط درایور MBTiles ارائه می‌شود.
مقدار رستر آن پیکسل برای همه یا زیرمجموعه‌ای از باندها.
مقدار مقیاس‌بندی‌نشده (unscaled) پیکسل در صورتی که یک Scale و/یا Offset روی باند اعمال شود.

پیکسل انتخاب‌شده از طریق مختصات x/y در خط فرمان درخواست می‌شود، یا از stdin خوانده می‌شود. هنگام خواندن مختصات از stdin می‌توان بیش از یک جفت مختصات را ارائه داد. به‌طور پیش‌فرض، مختصات صحیح pixel/line مورد انتظار است. با این حال، با استفاده از سوئیچ‌های -geoloc، -wgs84 یا -l_srs می‌توان موقعیت را در دستگاه‌های مختصات دیگر مشخص کرد.

گزارش پیش‌فرض در قالب متنی خوانا برای انسان است. در عوض، امکان درخواست خروجی xml با سوئیچ -xml وجود دارد.

به منظور اسکریپت‌نویسی، سوئیچ‌های -valonly و -lifonly برای محدود کردن خروجی به مقادیر واقعی پیکسل، یا فایل‌های LocationInfo شناسایی‌شده برای پیکسل ارائه شده‌اند.

پیش‌بینی می‌شود که قابلیت‌های گزارش‌دهی بیشتری در آینده به gdallocationinfo اضافه شود.

وضعیت خروج (EXIT STATUS)

این برنامه در صورت موفقیت کد وضعیت 0 و در صورت بروز خطا مقدار غیر صفر بازمی‌گرداند (خطاهای غیرمسدودکننده که به صورت هشدار صادر می‌شوند، اجرای موفقیت‌آمیز در نظر گرفته می‌شوند).

مثال‌ها (EXAMPLES)

مثال ۱: گزارش درباره پیکسل (256,256) روی فایل utm.tif

$ gdallocationinfo utm.tif 256 256
Report:
Location: (256P,256L)
Band 1:
    Value: 115

مثال ۲: پرس‌وجوی یک فایل VRT با ارائه موقعیت در WGS84 و دریافت نتیجه در قالب XML

$ gdallocationinfo -xml -wgs84 utm.vrt -117.5 33.75
<Report pixel="217" line="282">
    <BandReport band="1">
        <LocationInfo>
        <File>utm.tif</File>
        </LocationInfo>
        <Value>16</Value>
    </BandReport>
</Report>

مثال ۳: خواندن موقعیت‌ها از stdin

$ cat coordinates.txt
443020 3748359
441197 3749005
443852 3747743
$ cat coordinates.txt | gdallocationinfo -geoloc utmsmall.tif
Report:
  Location: (38P,49L)
  Band 1:
    Value: 214
Report:
  Location: (7P,38L)
  Band 1:
    Value: 107
Report:
  Location: (52P,59L)
  Band 1:
    Value: 148
$ cat coordinates.txt | gdallocationinfo -geoloc -valonly -E -field_sep , utmsmall.tif
443020,3748359,214
441197,3749005,107
443852,3747743,148

نویسندگان (AUTHORS)

Frank Warmerdam <warmerdam@pobox.com>

کپی‌رایت و تکثیر (COPYRIGHT)

1998-2026

August 18, 2026