GDAL-RASTER-FOOTPRINT(1)             GDAL             GDAL-RASTER-FOOTPRINT(1)

نام (NAME)
       gdal-raster-footprint - محاسبه ردپای یک مجموعه داده شطرنجی (رستر)

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


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

          نحوه استفاده: gdal raster footprint [OPTIONS] <INPUT>... <OUTPUT>

          محاسبه ردپای یک مجموعه داده رستر.

          آرگومان‌های موضعی (Positional arguments):
            -i, --input <INPUT>                                  مجموعه داده‌های رستر ورودی [تکرارپذیر] [الزامی] [در خطوط لوله در دسترس نیست]
            -o, --output <OUTPUT>                                مجموعه داده برداری خروجی [الزامی] [در خطوط لوله در دسترس نیست]

          گزینه‌های عمومی (Common Options):
            -h, --help                                           نمایش پیام راهنما و خروج
            --json-usage                                         نمایش نحوه استفاده به صورت سند JSON و خروج
            --config <KEY>=<VALUE>                               گزینه پیکربندی [تکرارپذیر]
            -q, --quiet                                          حالت بی‌صدا (بدون نوار پیشرفت یا پیام هشدار) [در خطوط لوله در دسترس نیست]

          گزینه‌ها (Options):
            -f, --of, --format, --output-format <OUTPUT-FORMAT>  قالب خروجی [در خطوط لوله در دسترس نیست]
            --co, --creation-option <KEY>=<VALUE>                گزینه ایجاد [تکرارپذیر] [در خطوط لوله در دسترس نیست]
            --lco, --layer-creation-option <KEY>=<VALUE>         گزینه ایجاد لایه [تکرارپذیر] [در خطوط لوله در دسترس نیست]
            --append                                             آیا الحاق به لایه موجود مجاز است [در خطوط لوله در دسترس نیست]
            --overwrite                                          آیا بازنویسی روی مجموعه داده خروجی موجود مجاز است [در خطوط لوله در دسترس نیست]
            --output-layer <OUTPUT-LAYER>                        نام لایه خروجی (پیش‌فرض: footprint)
            -b, --band <BAND>                                    باند(های) ورودی (شاخص مبتنی بر 1) [تکرارپذیر]
            --combine-bands <COMBINE-BANDS>                      تعیین نحوه ترکیب باندهای ماسک باندهای انتخابی جهت تولید یک باند ماسک منفرد پیش از برداری‌سازی. COMBINE-BANDS=union|intersection (پیش‌فرض: union)
            --overview <OVERVIEW>                                کدام سطح نمای کلی (overview) فایل منبع باید استفاده شود
                                                                 ناسازگار با --input-nodata
            --input-nodata <INPUT-NODATA>                        تنظیم مقادیر nodata برای باندهای ورودی. [1.. values]
                                                                 ناسازگار با --overview
            --coordinate-system <COORDINATE-SYSTEM>              سیستم مختصات مقصد. COORDINATE-SYSTEM=georeferenced|pixel
            --output-crs <OUTPUT-CRS>                            سیستم مرجع مختصات (CRS) خروجی
            --split-multipolygons                                آیا چندضلعی‌های چندبخشی (multipolygons) به چندین عارضه که هرکدام دارای یک چندضلعی منفرد هستند تقسیم شوند
            --convex-hull                                        آیا پوش محدب (convex hull) ردپا محاسبه شود
            --densify-distance <DENSIFY-DISTANCE>                حداکثر فاصله بین ۲ نقطه متوالی از هندسه خروجی.
            --simplify-tolerance <SIMPLIFY-TOLERANCE>            میزان تلورانس برای ادغام نقاط متوالی از هندسه خروجی.
            --min-ring-area <MIN-RING-AREA>                      حداقل مقدار برای مساحت یک حلقه
            --max-points <MAX-POINTS>                            حداکثر تعداد نقاط در هر هندسه خروجی (پیش‌فرض: 100)
            --location-field <LOCATION-FIELD>                    نام فیلدی که مسیر مجموعه داده ورودی در آن ذخیره خواهد شد. (پیش‌فرض: location)
                                                                 ناسازگار با --no-location-field
            --no-location-field                                  غیرفعال کردن ایجاد فیلد حاوی مسیر مجموعه داده ورودی
                                                                 ناسازگار با --location-field
            --absolute-path                                      آیا مسیر مجموعه داده ورودی به صورت یک مسیر مطلق ذخیره شود

          گزینه‌های پیشرفته (Advanced Options):
            --oo, --open-option <KEY>=<VALUE>                    گزینه‌های باز کردن [تکرارپذیر] [در خطوط لوله در دسترس نیست]
            --if, --input-format <INPUT-FORMAT>                  قالب‌های ورودی [تکرارپذیر] [در خطوط لوله در دسترس نیست]

توضیحات (DESCRIPTION)
       دستور gdal raster footprint ردپای یک فایل رستر را با در نظر گرفتن
       مقادیر داده‌نامعتبر (nodata) یا به طور کلی‌تر، باند ماسک متصل به باندهای
       رستر محاسبه می‌کند؛ چندضلعی‌ها یا چندضلعی‌های چندبخشی
       (polygons/multipolygons) متناظر با نواحی دارای پیکسل‌های معتبر را تولید
       کرده و آن‌ها را در یک فایل برداری خروجی می‌نویسد.

       از نسخه 3.12 نرم‌افزار GDAL، این الگوریتم می‌تواند بخشی از یک gdal
       pipeline باشد.

       ابزار gdal raster clean-collar می‌تواند به عنوان یک مرحله پیش‌پردازش برای
       ایجاد باندهای ماسک مناسب اجرا شود.
         [تصویر]

       نمونه‌ای از ردپای محاسبه‌شده با گزینه‌های پیش‌فرض gdal raster footprint.

       عملیات هندسی پس از برداری‌سازی (Post-vectorization) به ترتیب زیر اعمال
       می‌شوند:

       • تفکیک اختیاری (--split-multipolygons)

       • تراکم‌بخشی اختیاری (--densify-distance)

       • بازپرتوافکنی اختیاری (--output-crs)

       • فیلتر کردن اختیاری بر اساس حداقل مساحت حلقه (--min-ring-area)

       • اعمال اختیاری پوش محدب (--convex-hull)

       • ساده‌سازی اختیاری (--simplify-tolerance)

       • محدودسازی تعداد نقاط (--max-points)

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


خروجی GDALG (مجموعه داده درجا / جریانی)
       این برنامه از سریال‌سازی خط فرمان به عنوان یک فایل JSON با استفاده از
       قالب خروجی GDALG پشتیبانی می‌کند.  سپس فایل حاصل می‌تواند با استفاده از
       راه‌انداز (درایور) GDALG: GDAL Streamed Algorithm به عنوان یک مجموعه
       داده برداری باز شود و خط لوله مشخص‌شده را به صورت درجا (on-the-fly) یا
       جریانی (streamed) اعمال کند.

       نکته:
          با این حال، این الگوریتم به صورت ذاتی با حالت جریانی سازگار نیست. در
          نتیجه، یک مجموعه داده موقت در حافظه (in-memory) ایجاد خواهد شد که
          ممکن است هنگام باز شدن باعث صرف زمان پردازش قابل‌توجهی شود.

گزینه‌های اختصاصی برنامه (PROGRAM-SPECIFIC OPTIONS)

       --absolute-path
              نوشتن مسیر مطلق مجموعه داده ورودی را فعال می‌کند. به‌طور پیش‌فرض،
              نام فایل دقیقاً همان‌طور که در خط فرمان مشخص شده است در فیلد
              موقعیت مکانی (location) نوشته می‌شود.

       -b, --band <band>
              انتخاب یک <باند> ورودی برای پردازش. شماره‌گذاری باندها از ۱ آغاز
              می‌شود.  می‌توان از چندین سوییچ -b برای انتخاب مجموعه‌ای از باندهای
              ورودی استفاده کرد.  در صورت عدم تعیین، تمام باندها در نظر گرفته
              می‌شوند. نحوه ترکیب چندین باند توسط --combine-bands کنترل می‌شود.

       --combine-bands union|intersection
              تعیین می‌کند که باندهای ماسک باندهای انتخابی، پیش از برداری‌سازی
              چگونه ترکیب شوند تا یک باند ماسک منفرد ایجاد گردد.  مقدار پیش‌فرض
              union (اجتماع) است: بدین معنا که یک پیکسل در صورتی معتبر خواهد
              بود که دست‌کم در یکی از باندهای انتخابی معتبر باشد.  مقدار
              intersection (اشتراک) به این معناست که یک پیکسل تنها در صورتی
              معتبر است که در تمامی باندهای انتخابی معتبر باشد.

       --coordinate-system pixel|georeferenced
              سیستم مختصات مقصد. به‌طور پیش‌فرض اگر مجموعه داده ورودی دارای
              زمین‌مرجع (georeferenced) باشد، مقدار georeferenced در نظر گرفته
              می‌شود؛ بدین معنی که هندسه ردپا به صورت مختصات در سیستم مرجع
              مختصات (CRS) رستر (یا سیستم مشخص‌شده با --output-crs) بیان خواهد
              شد.  در صورت مشخص کردن pixel، مختصات هندسه ردپا به صورت شاخص‌های
              ستون و سطر (پیکسل) خواهند بود.

       --convex-hull
              در صورت تعیین این گزینه، پوش محدب چندضلعی‌ها (یا چندضلعی‌های
              چندبخشی) محاسبه می‌شود.

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

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

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

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

       --min-ring-area <value>
              حداقل مقدار برای مساحت یک حلقه.  واحد مساحت اگر
              --coordinate-system برابر با pixel باشد بر حسب پیکسل مربع، و در
              غیر این صورت بر حسب واحدهای زمین‌مرجع مجموعه داده برداری مقصد
              خواهد بود.  این گزینه پس از بازپرتوافکنی ناشی از --output-crs
              اعمال می‌شود.

       --no-location-field
              نوشتن مسیر مجموعه داده ورودی به عنوان یک فیلد در مجموعه داده
              برداری خروجی را غیرفعال می‌کند.

       --output-crs <CRS_DEF>
              سیستم مرجع مختصات (CRS) مقصد فایل خروجی. مقدار <CRS_DEF> می‌تواند
              هر یک از قالب‌های معمول GDAL/OGR، یک WKT کامل، PROJ.4، مقدار
              EPSG:n یا فایلی حاوی WKT باشد.  مشخص کردن این گزینه مستلزم
              --coordinate-system=georeferenced است.  ردپا از CRS رستر منبع به
              CRS مشخص‌شده بازپرتوافکنی (reproject) می‌شود.

       --output-layer <OUTPUT-LAYER>
              نام لایه خروجی. پیش‌فرض footprint است.

       --overview <index>
              مشخص کردن سطح نمای کلی (overview) فایل منبع که باید استفاده شود،
              در صورتی که نماهای کلی در رستر منبع موجود باشند. به‌طور پیش‌فرض،
              سطح وضوح کامل استفاده می‌شود. این شاخص بر پایه صفر است، یعنی 0 به
              معنای نخستین سطح نمای کلی می‌باشد.  این گزینه با --input-nodata
              ناسازگار (مانعة‌الجمع) است.

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

       --split-multipolygons
              در صورت مشخص شدن، چندضلعی‌های چندبخشی به چند عارضه مجزا شکسته
              می‌شوند که هر کدام تنها شامل یک چندضلعی منفرد خواهند بود.

گزینه‌های استاندارد (STANDARD OPTIONS)

       --append
              تعیین اینکه آیا افزودن عوارض به لایه(های) موجود مجاز است یا خیر.
              این گزینه همچنین در صورتی که مجموعه داده خروجی هنوز وجود نداشته
              باشد، آن را ایجاد می‌کند.

       --co, --creation-option <NAME>=<VALUE>
              بسیاری از قالب‌ها یک یا چند گزینه اختیاری ایجاد دارند که می‌توان
              از آن‌ها برای کنترل جزئیات فایل ایجادشده استفاده کرد. برای نمونه،
              راه‌انداز GeoTIFF از گزینه‌های ایجاد برای کنترل فشرده‌سازی و این‌که
              آیا فایل باید کاشی‌بندی‌شده (tiled) باشد پشتیبانی می‌کند.

              می‌تواند تکرار شود.

              گزینه‌های ایجاد موجود بر اساس راه‌انداز قالب متفاوت هستند و برخی
              از قالب‌های ساده هیچ گزینه ایجادی ندارند. فهرستی از گزینه‌های
              پشتیبانی‌شده برای یک قالب را می‌توان با گزینه خط فرمان --formats
              مشاهده کرد، اما مستندات مربوط به همان قالب مرجع قطعی اطلاعات در
              مورد گزینه‌های ایجاد راه‌انداز است.  مستندات اختصاصی قالب‌های
              Raster drivers را برای گزینه‌های مجاز ایجاد هر قالب ببینید.

       --if, --input-format <format>
              نام قالب/راه‌انداز برای باز کردن فایل(های) ورودی. عموماً نیازی به
              تعیین آن نیست، اما زمانی که تشخیص خودکار راه‌انداز در انتخاب
              راه‌انداز مناسب ناموفق باشد، می‌توان از آن برای چشم‌پوشی از تشخیص
              خودکار استفاده کرد.  این گزینه می‌تواند چندین بار برای تعیین
              چندین راه‌انداز کاندید تکرار شود.  توجه داشته باشید که این گزینه
              راه‌اندازها را مجبور به باز کردن مجموعه داده نمی‌کند؛ به‌ویژه برخی
              از راه‌اندازها نیازمندی‌هایی برای پسوند فایل دارند.

              می‌تواند تکرار شود.

       --lco, --layer-creation-option <NAME>=<VALUE>
              بسیاری از قالب‌ها یک یا چند گزینه اختیاری ایجاد لایه دارند که
              می‌توان از آن‌ها برای کنترل ویژگی‌های مربوط به لایه ایجادشده
              استفاده کرد. برای مثال، راه‌انداز GeoPackage از گزینه‌های ایجاد
              لایه برای کنترل شناسه عارضه یا نام ستون هندسه، تنظیم شناسه یا
              توضیحات و غیره پشتیبانی می‌کند.

              می‌تواند تکرار شود.

              گزینه‌های ایجاد لایه بسته به راه‌انداز قالب متفاوت هستند و برخی
              قالب‌های ساده اصلاً گزینه ایجاد لایه ندارند. فهرستی از گزینه‌های
              پشتیبانی‌شده برای یک قالب را می‌توان با گزینه خط فرمان --formats
              مشاهده کرد، اما مستندات آن قالب مرجع قطعی اطلاعات درباره
              گزینه‌های ایجاد لایه راه‌انداز است.  برای گزینه‌های مجاز ایجاد لایه
              در هر قالب، مستندات اختصاصی قالب Vector drivers را ببینید.

              توجه داشته باشید که گزینه‌های ایجاد لایه با گزینه‌های ایجاد مجموعه
              داده متفاوت هستند.

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

              می‌تواند تکرار شود.

       -f, --of, --format, --output-format <OUTPUT-FORMAT>
              کدام قالب برداری خروجی استفاده شود. مقادیر مجاز را می‌توان با
              دستور زیر به دست آورد: gdal --formats | grep vector | grep rw |
              sort

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

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

مثال‌ها (EXAMPLES)
   مثال ۱: نوشتن ردپای یک فایل GeoTIFF در یک فایل GeoJSON.

          gdal raster footprint my_raster.tif footprint.geojson

نویسنده (AUTHOR)
       Even Rouault <even.rouault@spatialys.com>

حق نشر (COPYRIGHT)
       1998-2026

                                August 18, 2026       GDAL-RASTER-FOOTPRINT(1)