GDAL_FOOTPRINT(1)                    GDAL                    GDAL_FOOTPRINT(1)

نام (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              GDAL_FOOTPRINT(1)