GDAL-RASTER-MOSAIC(1)

GDAL

GDAL-RASTER-MOSAIC(1)

نام (NAME)

gdal-raster-mosaic - ساخت یک موزاییک

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

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

کاربرد: gdal raster mosaic [OPTIONS] <INPUTS>... <OUTPUT>
ساخت یک موزاییک، به صورت مجازی (VRT) یا محقق‌شده (فیزیکی).
آرگومان‌های موضعی:
  -i, --input <INPUTS>                                            مجموعه‌داده‌های رستر ورودی (یا تعیین @<filename> برای اشاره به فایلی حاوی نام فایل‌ها) [۱.. مقدار] [الزامی] [در pipelineها در دسترس نیست]
  -o, --output <OUTPUT>                                           مجموعه‌دادهٔ رستر خروجی [الزامی] [در pipelineها در دسترس نیست]
گزینه‌های عمومی:
  -h, --help                                                      نمایش پیام راهنما و خروج
  --json-usage                                                    نمایش نحوهٔ استفاده به عنوان سند JSON و خروج
  --config <KEY>=<VALUE>                                          گزینهٔ پیکربندی [می‌تواند تکرار شود]
  -q, --quiet                                                     حالت بی‌صدا (بدون نوار پیشرفت یا پیام هشدار) [در pipelineها در دسترس نیست]
گزینه‌ها:
  -f, --of, --format, --output-format <OUTPUT-FORMAT>             قالب خروجی (مقدار "GDALG" مجاز است) [در pipelineها در دسترس نیست]
  --co, --creation-option <KEY>=<VALUE>                           گزینهٔ ساخت [می‌تواند تکرار شود] [در pipelineها در دسترس نیست]
  --overwrite                                                     تعیین اینکه آیا رونویسی مجموعه‌دادهٔ خروجی موجود مجاز است یا خیر [در pipelineها در دسترس نیست]
                                                                  مانعة‌الجمع با --append
  --append                                                        الحاق به عنوان یک زیرمجموعه‌داده به خروجی موجود [در pipelineها در دسترس نیست]
                                                                  مانعة‌الجمع با --overwrite
  -b, --band <BAND>                                               باند(های) ورودی (شاخص بر پایهٔ ۱) [می‌تواند تکرار شود]
  --absolute-path                                                 تعیین اینکه آیا مسیر مجموعه‌داده‌های ورودی باید به صورت یک مسیر مطلق ذخیره شود یا خیر
  --resolution <xres>,<yres>|same|average|common|highest|lowest>  تفکیک‌پذیری هدف (در واحدهای CRS مقصد) (پیش‌فرض: same)
  --bbox <BBOX>                                                   جعبهٔ محصورکنندهٔ هدف به صورت xmin,ymin,xmax,ymax (در واحدهای CRS مقصد)
  --target-aligned-pixels                                         گرد کردن محدودهٔ هدف بر اساس تفکیک‌پذیری هدف
  --input-nodata <INPUT-NODATA>                                   تنظیم مقادیر nodata برای باندهای ورودی. [۱.. مقدار]
  --output-nodata <OUTPUT-NODATA>                                 تنظیم مقادیر nodata در سطح باند مقصد. [۱.. مقدار]
  --hide-nodata                                                   باعث می‌شود باند مقصد NoData را گزارش نکند.
  --add-alpha                                                     هنگامی که رسترهای منبع باند آلفا ندارند، یک باند ماسک آلفا به مقصد اضافه می‌کند.
  --pixel-function <PIXEL-FUNCTION>                               تعیین یک تابع پیکسل برای محاسبهٔ مقدار خروجی از ورودی‌های همپوشان. PIXEL-FUNCTION=area|argmax|argmin|cmul|complex|conj|dB|dB2amp|dB2pow|diff|div|exp|expression|geometric_mean|harmonic_mean|imag|intensity|interpolate_exp|interpolate_linear|inv|log10|max|mean|median|min|mod|mode|mul|norm_diff|phase|polar|pow|quantile|real|reclassify|replace_nodata|round|scale|sqrt|sum
  --pixel-function-arg <NAME>=<VALUE>                             تعیین آرگومان(ها) برای ارسال به تابع پیکسل [می‌تواند تکرار شود]
گزینه‌های پیشرفته:
  --if, --input-format <INPUT-FORMAT>                             قالب‌های ورودی [می‌تواند تکرار شود] [در pipelineها در دسترس نیست]
  --oo, --open-option <KEY>=<VALUE>                               گزینه‌های باز کردن [می‌تواند تکرار شود] [در pipelineها در دسترس نیست]

توضیحات (DESCRIPTION)

این برنامه از فهرستی از مجموعه‌داده‌های GDAL ورودی، یک موزاییک می‌سازد که می‌تواند یک موزاییک مجازی در قالب VRT (Virtual Dataset)، یا در یک قالب رستر مرسوم‌تر مانند GeoTIFF باشد.

نویسه‌های عام (wildcard) مانند '*'، '?' یا '['] مربوط به VSIGlob() می‌توانند برای نام مجموعه‌داده‌های ورودی استفاده شوند، حتی برای فایل‌هایی که در سامانه‌های فایل شبکه‌ای مانند /vsis3/، /vsigs/، /vsiaz/ و غیره قرار دارند. همچنین اگر پیشوند نام یک مجموعه‌دادهٔ ورودی نویسهٔ @ باشد، فرض می‌شود که آن فایل حاوی فهرستی از نام‌های واقعی مجموعه‌داده‌ها (هر خط یک نام) برای استفاده به عنوان مجموعه‌داده‌های ورودی است.

دستور gdal raster mosaic بررسی‌هایی انجام می‌دهد تا اطمینان حاصل شود که همهٔ فایل‌هایی که در فایل حاصل قرار می‌گیرند دارای ویژگی‌های مشابهی هستند: تعداد باندها، سیستم تصویر (projection)، تفسیر رنگ (color interpretation) و غیره. در غیر این صورت، فایل‌هایی که با ویژگی‌های مشترک مطابقت نداشته باشند، نادیده گرفته خواهند شد.

از GDAL 3.12 به بعد، می‌توان یک تابع (مانند min، mean، median) را تعیین کرد (--pixel-function) تا مقادیر پیکسل از ورودی‌های همپوشان محاسبه شوند. اگر تابعی تعیین نشود، یا در نسخه‌های پیشین، ترتیب فهرست ورودی برای تعیین اولویت استفاده می‌شود. فایل‌هایی که در انتهای فهرست قرار دارند، فایل‌هایی هستند که محتوا از آن‌ها واکشی خواهد شد. توجه داشته باشید که nodata برای واکشی احتمالی داده‌ها از مجموعه‌داده‌های با اولویت پایین‌تر لحاظ خواهد شد، اما در حال حاضر، کانال آلفا برای انجام ترکیب آلفا (alpha compositing) در نظر گرفته نمی‌شود (بنابراین منبعی با 0=alpha که روی منبع دیگری قرار می‌گیرد، محتوای آن را بازنویسی خواهد کرد). این رفتار ممکن است در نسخه‌های بعدی تغییر کند.

از GDAL 3.12 به بعد، این دستور همچنین می‌تواند به عنوان گام نخست در gdal raster pipeline استفاده شود..SH "خروجی GDALG (مجموعه‌داده در لحظه / جریانی) (GDALG OUTPUT (ON-THE-FLY / STREAMED DATASET))"

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

گزینه‌های ویژه برنامه (PROGRAM-SPECIFIC OPTIONS)

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

--add-alpha: در صورتی که رستر مبدأ فاقد آن باشد، یک باند ماسک آلفا به خروجی اضافه می‌کند. عمدتاً برای منابع RGB (یا منابع مقیاس خاکستری) کاربرد دارد. باند آلفا در لحظه با مقدار 0 در نواحی فاقد رستر مبدأ، و با مقدار 255 در نواحی دارای رستر مبدأ پر می‌شود. اثر آن این است که یک نمایشگر RGBA نواحی بدون رسترهای مبدأ را به‌صورت شفاف و نواحی دارای رسترهای مبدأ را به‌صورت کدر و مات رندر می‌کند.

-b, --band <band>: یک <band> ورودی را برای پردازش انتخاب می‌کند. شماره‌گذاری باندها از 1 آغاز می‌شود. اگر باندهای ورودی تنظیم نشوند، همه باندها به خروجی اضافه خواهند شد. می‌توان از چندین سوییچ -b برای انتخاب مجموعه‌ای از باندهای ورودی استفاده کرد.

--bbox <xmin>,<ymin>,<xmax>,<ymax>: محدوده ارجاع‌جغرافیایی (georeferenced) فایل خروجی را تنظیم می‌کند. مقادیر باید در واحدهای ارجاع‌جغرافیایی بیان شوند. در صورت عدم تعیین، محدوده خروجی برابر با حداقل جعبه مرزی (minimum bounding box) مجموعه رسترهای مبدأ خواهد بود. پیکسل‌های درون محدوده خروجی که توسط رستر مبدأ پوشش داده نشده‌اند، به‌عنوان پیکسل‌های معتبر با مقدار صفر خوانده می‌شوند مگر اینکه مقدار NODATA با استفاده از --output-nodata مشخص شده باشد یا با --add-alpha یک باند ماسک آلفا اضافه گردد.

--hide-nodata: حتی اگر هر باندی حاوی مقدار nodata باشد، ارائه این گزینه باعث می‌شود باند خروجی NoData را گزارش نکند. این گزینه هنگامی که می‌خواهید رنگ پس‌زمینه مجموعه‌داده را کنترل کنید مفید است. با استفاده همزمان از گزینه --add-alpha، می‌توانید مجموعه‌داده‌ای آماده کنید که مقدار nodata را گزارش نمی‌دهد اما در نواحی فاقد داده، شفاف است.

--input-nodata <value>[,<value>]...: مقادیر nodata را برای باندهای ورودی تنظیم می‌کند (می‌توان مقادیر متفاوتی برای هر باند ارائه داد). اگر این گزینه مشخص نشود، تنظیمات درونی nodata در مجموعه‌داده‌های مبدأ (در صورت وجود) استفاده خواهند شد. مقدار تنظیم‌شده توسط این گزینه در عنصر NODATA از هر عنصر ComplexSource نوشته می‌شود.

--output-nodata <value>[,<value>]...: مقادیر nodata را در سطح باند خروجی تنظیم می‌کند (می‌توان مقادیر متفاوتی برای هر باند ارائه داد). اگر بیش از یک مقدار مشخص شود، تمام مقادیر باید در نقل‌قول قرار گیرند تا به‌عنوان یک آرگومان واحد سیستم‌عامل حفظ شوند (Example 1). اگر این گزینه مشخص نشود، تنظیمات درونی nodata در اولین مجموعه‌داده (در صورت وجود) استفاده خواهند شد. مقدار تنظیم‌شده با این گزینه در عنصر NoDataValue از هر VRTRasterBand element نوشته می‌شود. از مقدار None برای نادیده گرفتن تنظیمات nodata درونی در مجموعه‌داده‌های مبدأ استفاده کنید.

--pixel-function: نام تابعی را برای محاسبه یک مقدار از ورودی‌های هم‌پوشان مشخص می‌کند. برای مشاهده فهرستی از توابع پیکسل موجود، Built-in Pixel Functions را ببینید. اگر تابعی مشخص نشود، مقادیر از آخرین ورودی هم‌پوشان دریافت خواهند شد.
در نسخه 3.12 اضافه شد.

--pixel-function-arg: آرگومانی را برای ارائه به یک تابع پیکسل، در قالب <NAME>=<VALUE> مشخص می‌کند. می‌توان با تکرار این گزینه چندین آرگومان را تعیین کرد.
در نسخه 3.12 اضافه شد.

--resolution {<xres,yres>|same|highest|lowest|average}

در صورتی که تفکیک‌پذیری (resolution) تمام فایل‌های ورودی یکسان نباشد، پرچم --resolution به کاربر امکان می‌دهد تا نحوه محاسبه تفکیک‌پذیری خروجی را کنترل کند.

same، مقدار پیش‌فرض، بررسی می‌کند که آیا همه رسترهای مبدأ تفکیک‌پذیری یکسانی دارند یا خیر، و در غیر این صورت با خطا متوقف می‌شود.

highest کوچک‌ترین مقادیر ابعاد پیکسل را در میان مجموعه رسترهای مبدأ انتخاب می‌کند.

lowest بزرگ‌ترین مقادیر ابعاد پیکسل را در میان مجموعه رسترهای مبدأ انتخاب می‌کند.

average میانگین ابعاد پیکسل را در میان مجموعه رسترهای مبدأ محاسبه می‌کند.

common بزرگ‌ترین مقسوم‌علیه مشترک ابعاد پیکسل مبدأ را تعیین می‌کند، مثلاً 0.2 برای ابعاد پیکسل مبدأ 0.4 و 0.6.

<xres>,<yres>. مقادیر باید در واحدهای ارجاع‌جغرافیایی بیان شوند. هر دو باید مقادیری مثبت باشند.

--target-aligned-pixels: (پیکسل‌های هم‌تراز با هدف) مختصات محدوده فایل خروجی را با مقادیر --resolution تراز می‌کند، به‌گونه‌ای که محدوده تراز‌شده شامل حداقل محدوده باشد. تراز کردن به این معنی است که xmin / resx، ymin / resy، xmax / resx و ymax / resy مقادیر صحیح باشند.

--append: الحاق رستر ورودی به‌عنوان یک زیرمجموعه‌داده (subdataset) جدید به یک فایل خروجی موجود. تنها با درایورهایی کار می‌کند که از افزودن زیرمجموعه‌داده‌ها پشتیبانی می‌کنند؛ مانند GTiff -- GeoTIFF File Format و GPKG -- GeoPackage raster. همچنین اگر مجموعه‌داده خروجی هنوز وجود نداشته باشد، آن را ایجاد می‌کند.

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

بسیاری از فرمت‌ها یک یا چند گزینه اختیاری ساخت (creation option) دارند که می‌توان از آن‌ها برای کنترل جزئیات فایل ایجادشده استفاده کرد. برای نمونه، درایور GeoTIFF از گزینه‌های ساخت برای کنترل فشرده‌سازی و این‌که آیا فایل باید کاشی‌بندی (tiled) شود یا خیر، پشتیبانی می‌کند.

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

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

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

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

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

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

وضعیت خروج (EXIT STATUS)

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

مثال‌ها (EXAMPLES)

مثال ۱: ساخت یک موزاییک مجازی با رنگ پس‌زمینه آبی (RGB: 0 0 255)

gdal raster mosaic --hide-nodata --output-nodata=0,0,255 doq/*.tif doq_index.vrt

مثال ۲: ایجاد یک موزاییک Cloud Optimized GeoTIFF (COG) از تمام فایل‌های GeoTIFF در یک پوشه

از آنجا که اندازه فایل GeoTIFF حاصل بیش از 4 GB خواهد بود، از گزینه ساخت BIGTIFF=YES استفاده می‌شود.

gdal raster mosaic --output-format COG --creation-option BIGTIFF=YES *.tif mosaic.tif

Even Rouault <even.rouault@spatialys.com>

کپی‌رایت و تکثیر (COPYRIGHT)

1998-2026

August 18, 2026