GDAL-RASTER-INDEX(1)

GDAL

GDAL-RASTER-INDEX(1)

نام (NAME)

gdal-raster-index - ایجاد یک نمایه برداری از مجموعه‌داده‌های رستر

افزوده‌شده در نسخه 3.11.

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

Usage: gdal raster index [OPTIONS] <INPUT>... <OUTPUT>
ایجاد نمایه برداری از مجموعه‌داده‌های رستر.
آرگومان‌های مکانی:
  -i, --input <INPUT>                                  مجموعه‌داده‌های رستر ورودی [تکرارپذیر] [الزامی]
  -o, --output <OUTPUT>                                مجموعه‌داده برداری خروجی [الزامی]
گزینه‌های عمومی:
  -h, --help                                           نمایش پیام راهنما و خروج
  --json-usage                                         نمایش نحوه استفاده در قالب سند JSON و خروج
  --config <KEY>=<VALUE>                               گزینه پیکربندی [تکرارپذیر]
  -q, --quiet                                          حالت بی‌صدا (بدون نوار پیشرفت یا پیام هشدار) [در خطوط لوله در دسترس نیست]
گزینه‌ها:
  -f, --of, --format, --output-format <OUTPUT-FORMAT>  قالب خروجی
  --co, --creation-option <KEY>=<VALUE>                گزینه ایجاد [تکرارپذیر]
  --lco, --layer-creation-option <KEY>=<VALUE>         گزینه ایجاد لایه [تکرارپذیر]
  --overwrite                                          امکان بازنویسی مجموعه‌داده خروجی موجود
                                                       ناسازگار با --update
  --update                                             باز کردن مجموعه‌داده موجود در حالت به‌روزرسانی
                                                       ناسازگار با --overwrite
  --overwrite-layer                                    امکان بازنویسی لایه خروجی موجود
  --append                                             امکان الحاق به لایه موجود
  --nln, --output-layer <OUTPUT-LAYER>                 نام لایه خروجی
  --recursive                                          کاوش بازگشتی دایرکتوری‌های ورودی
  --filename-filter <FILENAME-FILTER>                  الگویی که نام فایل‌ها در دایرکتوری‌های ورودی باید از آن پیروی کنند (نویسه‌های عام '*' و '?') [تکرارپذیر]
  --min-pixel-size <MIN-PIXEL-SIZE>                    حداقل اندازه پیکسل بر حسب وسعت مکانی به ازای هر پیکسل (تفکیک‌پذیری) برای انتخاب رستر
  --max-pixel-size <MAX-PIXEL-SIZE>                    حداکثر اندازه پیکسل بر حسب وسعت مکانی به ازای هر پیکسل (تفکیک‌پذیری) برای انتخاب رستر
  --location-name <LOCATION-NAME>                      نام فیلد حاوی مسیر رستر (پیش‌فرض: location)
  --absolute-path                                      ذخیره مسیر مجموعه‌داده‌های ورودی به صورت مسیر مطلق
  --output-crs <OUTPUT-CRS>                            سامانه مرجع مختصات (CRS) خروجی
  --metadata <KEY>=<VALUE>                             افزودن متادیتای مجموعه‌داده [تکرارپذیر]
  --skip-errors                                        نادیده گرفتن خطاهای مربوط به مجموعه‌داده‌های ورودی
  --profile <PROFILE>                                  پروفایل مجموعه‌داده خروجی. PROFILE=none|STAC-GeoParquet (پیش‌فرض: none)
  --base-url <BASE-URL>                                آدرس پایه (Base URL) برای href در STAC-GeoParquet
  --id-method <ID-METHOD>                              نحوه استخراج 'id' در STAC-GeoParquet. ID-METHOD=filename|md5|metadata-item (پیش‌فرض: filename)
  --id-metadata-item <ID-METADATA-ITEM>                نام آیتم متادیتا مورد استفاده برای تعیین 'id' در STAC-GeoParquet (پیش‌فرض: id)
  --source-crs-field-name <SOURCE-CRS-FIELD-NAME>      نام فیلد جهت ذخیره CRS هر مجموعه‌داده
  --source-crs-format <SOURCE-CRS-FORMAT>              قالب نگارش CRS هر مجموعه‌داده. SOURCE-CRS-FORMAT=auto|WKT|EPSG|PROJ (پیش‌فرض: auto)

توضیحات (DESCRIPTION)

دستور gdal raster index یک مجموعه‌داده برداری ایجاد می‌کند که شامل یک رکورد برای هر فایل رستر ورودی، یک مشخصه حاوی نام فایل و یک هندسه چندضلعی مشخص‌کننده محدوده رستر است. این خروجی برای استفاده در MapServer به عنوان یک نمایه تایل‌های رستر (raster tileindex) مناسب است.

برای گسترشی از این دستور که فایل‌هایی جهت استفاده به عنوان ورودی برای درایور GTI ایجاد می‌کند، به gdal driver gti create مراجعه کنید.

گزینه‌های زیر در دسترس هستند:

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

--absolute-path: مسیر مطلق فایل‌های رستر در فایل نمایه ذخیره می‌شود. به طور پیش‌فرض، نام فایل‌های رستر دقیقاً همان‌گونه که در خط فرمان مشخص شده‌اند در فایل قرار می‌گیرند.

--base-url <BASE-URL>: افزوده‌شده در نسخه 3.13.
آدرس پایه (Base URL) برای ویژگی href از ویژگی id در یک نمایه STAC-GeoParquet.

--filename-filter <FILENAME-FILTER>: الگویی که نام فایل‌های موجود در دایرکتوری‌های ورودی باید از آن پیروی کنند. کاراکتر '*' یک نویسه عمومی (wildcard) است که با هر تعداد نویسه از جمله تهی تطابق می‌یابد. کاراکتر '?' یک نویسه عمومی است که با یک تک‌نویسه مطابقت دارد. مقایسه‌ها بدون توجه به بزرگی و کوچکی حروف (case-insensitive) انجام می‌شوند. می‌توان چندین فیلتر مشخص کرد.
برای مثال: --filename-filter "*.tif,*.tiff"

--id-metadata-item <ID-METADATA-ITEM>: افزوده‌شده در نسخه 3.13.
نام آیتم متادیتا برای تنظیم ویژگی id در STAC-GeoParquet. پیش‌فرض id است.

--id-method filename|md5|metadata-item: افزوده‌شده در نسخه 3.13.
نحوه اشتقاق ویژگی id در STAC-GeoParquet:

filename (پیش‌فرض): فقط نام فایل (بدون دایرکتوری، ولی با پسوند) استفاده می‌شود.
md5: مقدار MD5Sum فایل محاسبه شده و نام فایل به آن الحاق می‌شود.
metadata-item: مقدار آیتم متادیتای مشخص‌شده با --id-metadata-item از هر مجموعه‌داده مبدأ استفاده می‌شود.

--location-name <LOCATION-NAME>: نام فیلد خروجی برای نگهداری مسیر یا موقعیت رسترهای نمایه‌شده. نام فیلد پیش‌فرض location است.

--max-pixel-size <val>: حداکثر اندازه پیکسل بر حسب وسعت مکانی به ازای هر پیکسل (تفکیک‌پذیری) که یک رستر باید داشته باشد تا انتخاب شود. اندازه پیکسل پس از بازتصویر وسعت آن به CRS مقصد که توسط --output-crs تعیین شده است، سنجیده می‌شود.

--metadata <KEY>=<VALUE>: نوشتن یک آیتم متادیتای دلخواه لایه، برای قالب‌هایی که از متادیتای لایه پشتیبانی می‌کنند. این گزینه می‌تواند تکرار شود.

--min-pixel-size <val>: حداقل اندازه پیکسل بر حسب وسعت مکانی به ازای هر پیکسل (تفکیک‌پذیری) که یک رستر باید داشته باشد تا انتخاب شود. اندازه پیکسل پس از بازتصویر وسعت آن به CRS مقصد که توسط --output-crs تعیین شده است، سنجیده می‌شود.

--output-crs <OUTPUT-CRS>: هندسه‌های فایل‌های ورودی به سامانه مرجع مختصات مقصد مورد نظر تبدیل خواهند شد. حالت پیش‌فرض، چندضلعی‌های مستطیلی ساده‌ای در همان سامانه مرجع مختصات رسترهای ورودی ایجاد می‌کند.

--profile none|STAC-GeoParquet: افزوده‌شده در نسخه 3.13.
پروفایل مجموعه‌داده خروجی را تعیین می‌کند. در صورت انتخاب STAC-GeoParquet، یک فایل Parquet منطبق بر مشخصات STAC-GeoParquet ایجاد می‌شود (مشروط بر آنکه قالب Parquet نیز انتخاب شده باشد). چنین فایلی توسط درایور GTI driver قابل خواندن است. تنظیم STAC-GeoParquet همچنین به طور ضمنی سامانه مرجع مختصات مقصد را روی EPSG:4326 تنظیم می‌کند.

--recursive: تعیین می‌کند که آیا دایرکتوری‌های ورودی باید به صورت بازگشتی کاوش شوند یا خیر.

--skip-errors: افزوده‌شده در نسخه 3.12.
نادیده گرفتن خطاهای مربوط به مجموعه‌داده‌های ورودی.

--source-crs-field-name <SOURCE-CRS-FIELD-NAME>: نام فیلد برای ذخیره CRS هر تایل. این نام فیلد می‌تواند به عنوان مقدار کلمه کلیدی TILESRS در MapServer استفاده شود.

--source-crs-format auto|WKT|EPSG|PROJ: قالبی که CRS هر تایل باید بر اساس آن نوشته شود. انواع مجاز عبارتند از: auto، WKT، EPSG و PROJ. این گزینه باید به همراه --source-crs-field-name استفاده شود.

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

--append: امکان الحاق عوارض به لایه یا لایه‌های موجود را فراهم می‌کند. در صورتی که مجموعه‌داده خروجی هنوز وجود نداشته باشد، آن را نیز ایجاد می‌کند.

--co, --creation-option <NAME>=<VALUE>

بسیاری از قالب‌ها یک یا چند گزینه اختیاری ایجاد دارند که می‌توانند برای کنترل ویژگی‌های خاص فایل ایجادشده استفاده شوند. به عنوان مثال، درایور GeoTIFF از گزینه‌های ایجاد برای کنترل فشرده‌سازی و تایل‌بندی شدن فایل پشتیبانی می‌کند.

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

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

--lco, --layer-creation-option <NAME>=<VALUE>

بسیاری از قالب‌ها یک یا چند گزینه اختیاری ایجاد لایه دارند که می‌توانند برای کنترل ویژگی‌های خاص لایه ایجادشده به کار روند. برای مثال، درایور GeoPackage از گزینه‌های ایجاد لایه برای کنترل شناسه عارضه یا نام ستون هندسه، تنظیم شناسه یا توضیحات و غیره پشتیبانی می‌کند.

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

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

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

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

--nln, --output-layer <LAYER>: تعیین نامی برای لایه برداری خروجی.

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

--overwrite-layer: امکان بازنویسی لایه برداری خروجی موجود را فراهم می‌کند.

--update: تعیین می‌کند که مجموعه‌داده خروجی باید در حالت به‌روزرسانی باز شود. مستلزم آن است که از قبل وجود داشته باشد.

کد وضعیت بازگشتی (RETURN STATUS CODE)

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

مثال‌ها (EXAMPLES)

مثال ۱

ایجاد یک GeoPackage حاوی یک رکورد برای هر تصویر کشف‌شده توسط این ابزار در پوشه doq. هر رکورد حاوی اطلاعاتی است که به مکان تصویر اشاره دارد و همچنین یک شکل مستطیل محدودکننده که مرزهای تصویر را نشان می‌دهد:

gdal raster index doq/*.tif doq_index.gpkg

مثال ۲

از گزینه --output-crs نیز می‌توان برای تبدیل تمام هندسه‌های رستر ورودی به یک سیستم تصویر خروجی یکسان استفاده کرد:

gdal raster index --output-crs EPSG:4326 --source-crs-field-name=src_srs *.tif tile_index_mixed_crs.gpkg

مثال ۳: ایجاد یک نمایه منطبق بر STAC-GeoParquet

gdal raster index --profile STAC-GeoParquet  *.tif index.parquet

نویسنده (AUTHOR)

Even Rouault <even.rouault@spatialys.com>

حق نشر (COPYRIGHT)

1998-2026

August 18, 2026