نام (NAME)

gdal_footprint - محاسبه ردپا (محدوده پوشش) یک رستر

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

Usage: gdal_footprint [--help] [--long-usage] [--help-general]
                      [-b <band>]... [-combine_bands VAR]
                      [[-ovr <index>]|[-srcnodata "<value>[ <value>]..."]]
                      [-t_cs VAR] [-t_srs <srs_def>] [-split_polys]
                      [-convex_hull] [-densify <value>] [-simplify <value>]
                      [-min_ring_area <value>] [-max_points <value>|unlimited]
                      [--quiet] [-oo <NAME>=<VALUE>]... [-of <output_format>]
                      [[-location_field_name <field_name>]|[-no_location]]
                      [-write_absolute_path] [-lco <NAME>=<VALUE>]...
                      [-dsco <NAME>=<VALUE>]... [-lyr_name <value>] [-overwrite]
                      <src_filename> <dst_filename>

توضیحات (DESCRIPTION)

ابزار gdal_footprint می‌تواند برای محاسبه ردپا (Footprint) یا محدوده پوشش یک فایل رستری با در نظر گرفتن مقادیر nodata (یا به طور کلی‌تر باند ماسک متصل به باندهای رستر)، و تولید چندضلعی‌ها/چندچندضلعی‌ها (Polygons/MultiPolygons) متناظر با نواحی دارای پیکسل‌های معتبر، و نوشتن در یک فایل برداری خروجی استفاده شود.

ابزار nearblack می‌تواند به عنوان یک مرحله پیش‌پردازش جهت تولید باندهای ماسک مناسب اجرا شود.

نکته کاربردی:

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

مشاهده کنید: gdal raster footprint.

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

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

-q, --quiet: عدم نمایش پیام‌های پیشرفت و سایر خروجی‌های غیرخطا (حالت بی‌صدا).

-b <band>: باند(های) مورد نظر. بین ۱ تا تعداد باندهای رستر. می‌تواند چندین بار تعیین شود. در صورت عدم تعیین، تمام باندها لحاظ می‌شوند. نحوه ترکیب باندهای مختلف با استفاده از -combine_bands کنترل می‌شود.

-combine_bands union|intersection: تعیین نحوه ترکیب باندهای ماسک مربوط به باندهای انتخاب‌شده برای تولید یک باند ماسک منفرد، پیش از برداری‌سازی. مقدار پیش‌فرض union است: یعنی یک پیکسل در صورتی معتبر است که حداقل برای یکی از باندهای انتخاب‌شده معتبر باشد. intersection به این معناست که یک پیکسل تنها در صورتی معتبر است که برای تمام باندهای انتخاب‌شده معتبر باشد.

-ovr <index>: تعیین اینکه کدام سطح نمای کلی (Overview) از فایل منبع باید استفاده شود، زمانی که نماهای کلی روی رستر منبع موجود باشند. به‌طور پیش‌فرض از سطح وضوح کامل استفاده می‌شود. شاخص بر پایه ۰ است، یعنی ۰ بیانگر اولین سطح نمای کلی است. این گزینه با -srcnodata ناسازگار و مانعة‌الجمع است.

-srcnodata "<value>[ <value>]...": تنظیم مقادیر nodata برای باندهای ورودی (می‌توان مقادیر متفاوتی برای هر باند ارائه داد). اگر یک مقدار واحد مشخص شود، برای تمام باندهای انتخاب‌شده اعمال می‌شود. اگر بیش از یک مقدار ارائه شود، باید به تعداد باندهای انتخاب‌شده مقدار وجود داشته باشد، و تمام مقادیر باید در علامت نقل‌قول (کوتیشن) قرار گیرند تا به عنوان یک آرگومان واحد به سیستم‌عامل فرستاده شوند. اگر این گزینه مشخص نشود، باند ماسک ذاتی هر یک از باندهای انتخاب‌شده استفاده خواهد شد.

-t_cs pixel|georef: دستگاه مختصات هدف. به‌طور پیش‌فرض اگر مجموعه‌داده ورودی دارای ارجاع مکانی (زمین‌مرجع) باشد، georef اعمال می‌شود، به این معنی که هندسه ردپا به صورت مختصات در دستگاه مرجع مکانی (CRS) رستر (یا سیستم تعیین‌شده با -t_srs) بیان خواهد شد. در صورت تعیین pixel، مختصات هندسه ردپا شاخص‌های ستون و سطر خواهند بود.

-t_srs <srs_def>: دستگاه مرجع مکانی (CRS) هدف برای فایل خروجی. <srs_def> می‌تواند هر یک از قالب‌های متداول GDAL/OGR، قالب کامل WKT، عبارت PROJ.4، شناسه EPSG:n یا فایلی حاوی WKT باشد. تعیین این گزینه به منزله -t_cs georef است. ردپا از CRS رستر مبدأ به CRS تعیین‌شده بازتصویرسازی می‌شود.

-split_polys: در صورت تعیین، چندچندضلعی‌ها (Multipolygons) به چندین عارضه تفکیک می‌شوند که هر یک شامل یک چندضلعی منفرد است.

-convex_hull: در صورت تعیین، پوش محدب (Convex Hull) چندضلعی‌ها (یا چندچندضلعی‌ها) محاسبه می‌شود.

-densify <value>: مقدار مشخص‌شده برای این گزینه، حداکثر فاصله مجاز بین ۲ نقطه متوالی از هندسه خروجی است. واحد فاصله در صورت برابر بودن -t_cs با pixel بر حسب پیکسل، یا در غیر این صورت بر حسب واحدهای زمین‌مرجع رستر مبدأ است. این گزینه پیش از بازتصویرسازی حاصل از -t_srs اعمال می‌شود.

-simplify <value>: مقدار تعیین‌شده برای این گزینه، میزان رواداری (Tolerance) مورد استفاده برای ادغام نقاط متوالی هندسه خروجی با استفاده از روش OGRGeometry::Simplify() است. واحد فاصله در صورت برابر بودن -t_cs با pixel بر حسب پیکسل، یا در غیر این صورت بر حسب واحدهای زمین‌مرجع مجموعه‌داده برداری هدف است. این گزینه پس از بازتصویرسازی حاصل از -t_srs اعمال می‌شود.

-min_ring_area <value>: حداقل مقدار مساحت یک حلقه (Ring). واحد مساحت در صورت برابر بودن -t_cs با pixel بر حسب پیکسل مربع، یا در غیر این صورت بر حسب واحدهای زمین‌مرجع مجموعه‌داده برداری هدف است. این گزینه پس از بازتصویرسازی حاصل از -t_srs اعمال می‌شود.

-max_points <value>|unlimited: حداکثر تعداد نقاط هر هندسه خروجی (بدون احتساب نقطه پایانی هر حلقه، که همواره منطبق بر نقطه اول است). مقدار پیش‌فرض ۱۰۰ است. می‌توان از unlimited برای حذف این محدودیت استفاده کرد.

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

-of <ogr_format>: انتخاب قالب خروجی. از نام کوتاه قالب استفاده کنید. در صورت عدم تعیین، از روی پسوند فایل حدس زده می‌شود.

-location_field_name <field_name>: در نسخه 3.9.0 اضافه شد.
نام فیلدی را در مجموعه‌داده برداری حاصل تعیین می‌کند که مسیر مجموعه‌داده ورودی در آن ذخیره خواهد شد. نام پیش‌فرض فیلد "location" است. برای جلوگیری از نوشتن مسیر مجموعه‌داده ورودی، از -no_location استفاده کنید.

-no_location: در نسخه 3.9.0 اضافه شد.
نوشتن مسیر مجموعه‌داده ورودی به عنوان یک فیلد در مجموعه‌داده برداری خروجی را غیرفعال می‌کند.

-write_absolute_path: در نسخه 3.9.0 اضافه شد.
نوشتن مسیر مطلق مجموعه‌داده ورودی را فعال می‌کند. به‌طور پیش‌فرض، نام فایل دقیقاً همان‌طور که در خط فرمان وارد شده در فیلد مکان نوشته می‌شود.

-lco <NAME>=<VALUE>: گزینه ایجاد لایه (مختص قالب).

-dsco <NAME>=<VALUE>: گزینه ایجاد مجموعه‌داده (مختص قالب).

-lyr_name <value>: نام لایه هدف. در صورت عدم تعیین، برابر با footprint خواهد بود.

-overwrite: بازنویسی لایه هدف در صورت وجود.

<src_filename>: نام فایل رستری مبدأ.

<dst_filename>: نام فایل برداری مقصد. اگر فایل و لایه خروجی وجود داشته باشند، ردپای جدید به آن‌ها الحاق می‌شود، مگر اینکه از -overwrite استفاده شود.

عملیات هندسی پس از برداری‌سازی به ترتیب زیر اعمال می‌شوند:

تفکیک اختیاری چندضلعی‌ها (-split_polys)
متراکم‌سازی اختیاری نقاط (-densify)
بازتصویرسازی اختیاری (-t_srs)
فیلتر کردن اختیاری بر اساس حداقل مساحت حلقه (-min_ring_area)
اعمال اختیاری پوش محدب (-convex_hull)
ساده‌سازی اختیاری (-simplify)
محدود کردن تعداد نقاط (-max_points)

کد وضعیت خروجی (RETURN STATUS CODE)

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

رابط سی (C API)

این ابزار از طریق C نیز با تابع GDALFootprint() قابل فراخوانی است.

مثال‌ها (EXAMPLES)

مثال ۱: محاسبه ردپای یک فایل GeoTIFF به عنوان یک فایل GeoJSON

gdal_footprint -t_srs EPSG:4326 input.tif output.geojson

ردپا با استفاده از مختصات طول و عرض جغرافیایی WGS84 نوشته خواهد شد، بدون توجه به دستگاه مرجع مکانی مورد استفاده در رستر ورودی.

نویسنده (AUTHOR)

Even Rouault <even.rouault@spatialys.com>

حق نشر (COPYRIGHT)

1998-2026

August 18, 2026