| 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) اعمال کند.
نکته:
گزینههای اختصاصی برنامه (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 |