| GDALBUILDVRT(1) | GDAL | GDALBUILDVRT(1) |
نام (NAME)
gdalbuildvrt - ساخت یک VRT از فهرستی از مجموعه‌داده‌ها.
خلاصه دستور (SYNOPSIS)
gdalbuildvrt [--help] [--long-usage] [--help-general]
[--quiet]
[[-strict]|[-non_strict]]
[-tile_index <field_name>]
[-resolution user|average|common|highest|lowest|same]
[-tr <xres> <yres>] [-input_file_list <filename>]
[[-separate]|[-pixel-function <function>]]
[-pixel-function-arg <NAME>=<VALUE>]...
[-allow_projection_difference] [-sd <n>] [-tap]
[-te <xmin> <ymin> <xmax> <ymax>] [-addalpha] [-b <band>]...
[-hidenodata] [-overwrite]
[-srcnodata "<value>[ <value>]..."]
[-vrtnodata "<value>[ <value>]..."] [-a_srs <srs_def>]
[-r nearest|bilinear|cubic|cubicspline|lanczos|average|mode]
[-oo <NAME>=<VALUE>]... [-co <NAME>=<VALUE>]...
[-ignore_srcmaskband]
[-nodata_max_mask_threshold <threshold>]
<vrt_dataset_name> [<src_dataset_name>]...
توضیحات (DESCRIPTION)
این برنامه یک VRT (Virtual Dataset) رستری ایجاد می‌کند که موزاییکی از فهرستی از مجموعه‌داده‌های ورودی GDAL است. فهرست مجموعه‌داده‌های ورودی GDAL را می‌توان در انتهای خط فرمان مشخص کرد، برای فهرست‌های بسیار طولانی در یک فایل متنی (یک نام فایل در هر خط) قرار داد، یا می‌تواند یک tileindex در MapServer باشد (ابزار gdaltindex را ببینید). در صورت استفاده از نمایه کاشی، تمام ورودی‌های موجود در نمایه کاشی به VRT اضافه خواهند شد.
نکته:
نکته کاربردی:
دستورات gdal raster mosaic و gdal raster stack را ببینید.
با گزینهٔ -separate، هر ورودی در یک باند جداگانه در مجموعه‌دادهٔ VRT قرار می‌گیرد. در غیر این صورت، فایل‌ها به عنوان رسترهای منبعِ یک موزاییک بزرگ‌تر در نظر گرفته می‌شوند و فایل VRT همان تعداد باند فایل‌های ورودی را خواهد داشت.
اگر یک مجموعه‌دادهٔ GDAL از چندین زیرمجموعه‌داده (subdataset) تشکیل شده باشد و دارای 0 باند رستری باشد، همهٔ زیرمجموعه‌داده‌ها به جای خود مجموعه‌داده به VRT اضافه خواهند شد.
دستور gdalbuildvrt بررسی‌هایی انجام می‌دهد تا اطمینان حاصل کند همهٔ فایل‌هایی که در VRT نهایی قرار می‌گیرند دارای ویژگی‌های مشابهی هستند: تعداد باندها، سیستم تصویر، تفسیر رنگ و غیره. در غیر این صورت، فایل‌هایی که با ویژگی‌های مشترک مطابقت نداشته باشند نادیده گرفته می‌شوند مگر اینکه از گزینهٔ -strict استفاده شود. (این موضوع تنها در حالت پیش‌فرض صادق است و هنگام استفاده از گزینهٔ -separate اعمال نمی‌شود)
از نسخه GDAL 3.12 به بعد، می‌توان تابعی (مانند min، mean، median) را مشخص کرد (-pixel-function) تا مقادیر پیکسل‌ها را از ورودی‌های دارای هم‌پوشانی محاسبه کند. اگر هیچ تابعی مشخص نشود، یا در نسخه‌های قدیمی‌تر، ترتیب فهرست ورودی برای تعیین اولویت استفاده می‌شود. فایل‌هایی که در انتهای فهرست قرار دارند، فایل‌هایی هستند که محتوا از آن‌ها واکشی خواهد شد. توجه داشته باشید که nodata برای واکشی احتمالی داده‌ها از مجموعه‌داده‌های با اولویت پایین‌تر در نظر گرفته می‌شود، اما در حال حاضر، کانال آلفا برای ترکیب آلفا (alpha compositing) در نظر گرفته نمی‌شود (بنابراین منبعی با alpha=0 که روی منبع دیگری قرار می‌گیرد، محتوای آن را بازنویسی خواهد کرد). این رفتار ممکن است در نسخه‌های بعدی تغییر کند.
- --help
- نمایش این پیام راهنما و خروج.
- --help-general
- نمایش پیام کوتاهی درباره نحوه استفاده از گزینه‌های عمومی خط فرمان GDAL و خروج.
- -q, --quiet
- عدم نمایش پیام‌های پیشرفت و سایر خروجی‌های غیرخطا.
- -tileindex <field_name>
- استفاده از مقدار مشخص‌شده به عنوان فیلد نمایهٔ کاشی، به جای مقدار پیش‌فرض که 'location' است.
- -resolution {highest|lowest|average|user|same}
- در صورتی که
تفکیک‌پذیری
(رزولوشن)
همه
فایل‌های
ورودی
یکسان
نباشد،
پرچم -resolution به
کاربر
امکان
می‌دهد
نحوه
محاسبه
تفکیک‌پذیری
خروجی را
کنترل کند.
گزینهٔ highest کوچک‌ترین مقادیر ابعاد پیکسل را در میان مجموعهٔ رسترهای منبع انتخاب می‌کند.
گزینهٔ lowest بزرگ‌ترین مقادیر ابعاد پیکسل را در میان مجموعهٔ رسترهای منبع انتخاب می‌کند.
گزینهٔ average حالت پیش‌فرض است و میانگین ابعاد پیکسل را در میان مجموعهٔ رسترهای منبع محاسبه می‌کند.
گزینهٔ user باید در ترکیب با گزینهٔ -tr برای مشخص کردن تفکیک‌پذیری هدف استفاده شود.
گزینهٔ same (اضافه‌شده در GDAL 3.11) بررسی می‌کند که همه رسترهای منبع تفکیک‌پذیری یکسانی داشته باشند و در غیر این صورت با خطا خارج می‌شود.
گزینهٔ common (اضافه‌شده در GDAL 3.11) بزرگ‌ترین مقسوم‌علیه مشترک (ب.م.م) ابعاد پیکسل منبع را تعیین می‌کند، به عنوان مثال 0.2 برای ابعاد پیکسل منبع 0.4 و 0.6.
- -tr <xres> <yres>
- تنظیم تفکیک‌پذیری هدف. مقادیر باید بر حسب واحدهای زمین‌مرجع بیان شوند. هر دو باید مقادیر مثبتی باشند. مشخص کردن این مقادیر مسلماً با مقادیر highest|lowest|average در گزینهٔ -resolution ناسازگار است.
- -tap
- (پیکسل‌های تراز شده با هدف یا target aligned pixels) مختصات محدودهٔ فایل خروجی را با مقادیر -tr تراز می‌کند، به‌گونه‌ای که محدودهٔ تراز شده شامل حداقل محدوده باشد. تراز کردن به این معنی است که مقادیر xmin / resx، ymin / resy، xmax / resx و ymax / resy مقادیری صحیح باشند.
- -te <xmin> <ymin> <xmax> <ymax>
- تنظیم محدوده‌های زمین‌مرجع شدهٔ فایل VRT. مقادیر باید بر حسب واحدهای زمین‌مرجع بیان شوند. در صورت عدم تعیین، محدودهٔ VRT حداقل کادر محصورکننده (bounding box) مجموعهٔ رسترهای منبع خواهد بود. پیکسل‌های درون محدودهٔ VRT که توسط یک رستر منبع پوشش داده نشده‌اند، به عنوان پیکسل‌های معتبر با مقدار صفر خوانده می‌شوند مگر اینکه یک مقدار NODATA با استفاده از -vrtnodata مشخص شده باشد یا یک باند ماسک آلفا با -addalpha اضافه شود.
- -addalpha
- در صورتی که رستر منبع فاقد باند ماسک آلفا باشد، یک باند به VRT اضافه می‌کند. عمدتاً برای منابع RGB (یا منابع در مقیاس خاکستری) مفید است. باند آلفا در لحظه با مقدار 0 در نواحی فاقد رستر منبع، و با مقدار 255 در نواحی دارای رستر منبع پر می‌شود. اثر آن این است که یک نمایشگر RGBA، نواحی فاقد رستر منبع را شفاف و نواحی دارای رستر منبع را کدر رندر می‌کند. این گزینه با -separate سازگار نیست.
- -hidenodata
- حتی اگر هر باندی حاوی مقدار nodata باشد، ارائه این گزینه باعث می‌شود باند VRT مقدار NoData را گزارش نکند. زمانی که می‌خواهید رنگ پس‌زمینه مجموعه‌داده را کنترل کنید مفید است. با استفاده از این گزینه همراه با گزینهٔ -addalpha، می‌توانید مجموعه‌داده‌ای آماده کنید که مقدار nodata را گزارش نمی‌کند اما در نواحی بدون داده شفاف است.
- -srcnodata "<value>[ <value>]..."
- تنظیم مقادیر nodata برای باندهای ورودی (می‌توان مقادیر متفاوتی برای هر باند ارائه کرد). اگر بیش از یک مقدار مشخص شود، همهٔ مقادیر باید در علامت نقل‌قول قرار گیرند تا به عنوان یک آرگومان واحد در سیستم‌عامل حفظ شوند. اگر این گزینه مشخص نشود، تنظیمات ذاتی nodata در مجموعه‌داده‌های منبع (در صورت وجود) استفاده خواهد شد. مقدار تعیین‌شده توسط این گزینه در عنصر NODATA از هر عنصر ComplexSource نوشته می‌شود. برای نادیده گرفتن تنظیمات ذاتی nodata در مجموعه‌داده‌های منبع، از مقدار None استفاده کنید.
از GDAL 3.3 به بعد، اگر یک منبع دارای یک باند ماسک (باند ماسک داخلی/خارجی، یا باند آلفا) باشد، به‌طور پیش‌فرض یک عنصر <ComplexSource> با عنصر فرزند <UseMaskBand>true</UseMaskBand> ایجاد می‌شود تا به راه‌انداز VRT دستور دهد از باند ماسک منبع برای ماسک کردن پیکسل‌های در حال ترکیب استفاده کند. این یک تعمیم از عنصر NODATA است. هنگام تعیین گزینهٔ -ignore_srcmaskband، باند ماسک منابع در نظر گرفته نخواهد شد و در صورت هم‌پوشانی میان منابع، آخرین منبع بر منابع قبلی در نواحی هم‌پوشانی بازنویسی خواهد شد.
- -nodata_max_mask_threshold <threshold>
- در نسخه 3.9
اضافه شد.
یک منبع <NoDataFromMaskSource> درج می‌کند که مقدار منبع را در صورتی که مقدار باند ماسک منبع کمتر یا مساوی آستانه باشد، با مقدار -vrtnodata (یا 0 در صورت عدم تعیین) جایگزین می‌کند. این گزینه معمولاً برای تبدیل یک تصویر R,G,B,A به یک تصویر R,G,B با مقدار NoData استفاده می‌شود.
- -b <band>
- انتخاب یک <band> ورودی برای پردازش. شماره‌گذاری باندها از 1 است. اگر باندهای ورودی تعیین نشوند، تمام باندها به VRT اضافه خواهند شد. می‌توان از چندین سوئیچ -b برای انتخاب مجموعه‌ای از باندهای ورودی استفاده کرد.
- -sd <n>
- اگر مجموعه داده ورودی شامل چندین زیرمجموعه داده (subdataset) باشد، از زیرمجموعه داده با شماره تعیین‌شده (شروع از 1) استفاده می‌کند. این روش جایگزینی برای ارائه نام کامل زیرمجموعه داده به عنوان ورودی به ابزار است.
- -vrtnodata "<value>[ <value>]..."
- تنظیم مقادیر nodata در سطح باند VRT (می‌توان مقادیر متفاوتی را برای هر باند ارائه داد). اگر بیش از یک مقدار ارائه شود، همه مقادیر باید در علامت نقل‌قول قرار گیرند تا به عنوان یک آرگومان واحد در سیستم‌عامل حفظ شوند (مثال 4). اگر این گزینه مشخص نشود، از تنظیمات nodata ذاتی در اولین مجموعه داده (در صورت وجود) استفاده خواهد شد. مقدار تعیین‌شده با این گزینه در عنصر NoDataValue مربوط به هر VRTRasterBand element نوشته می‌شود. از مقدار None برای نادیده گرفتن تنظیمات nodata ذاتی در مجموعه‌داده‌های منبع استفاده کنید.
- -separate
- قرار دادن
هر فایل
ورودی در یک
باند
جداگانه.
مثال 3 را
ببینید.
برخلاف
حالت
پیش‌فرض،
نیازی نیست
که همه
باندها نوع
داده
یکسانی
داشته
باشند. این
گزینه با
-pixel-function
ناسازگار
(مانعة‌الجمع)
است.
از GDAL 3.8 به بعد، تمام باندهای هر فایل ورودی به عنوان باندهای مجزای VRT اضافه می‌شوند، مگر اینکه -b برای انتخاب زیرمجموعه‌ای از آن‌ها تعیین شده باشد. پیش از GDAL 3.8، فقط اولین باند هر فایل ورودی در یک باند جدید VRT قرار می‌گرفت و -b نادیده گرفته می‌شد.
- -pixel-function
- تعیین نام
یک تابع
برای
محاسبه
مقدار از
ورودی‌های
دارای
هم‌پوشانی.
برای
مشاهده
فهرستی از
توابع
پیکسل
موجود، به
Built-in Pixel Functions
مراجعه
کنید. اگر
هیچ تابعی
تعیین
نشود،
مقادیر از
آخرین
ورودی
دارای
هم‌پوشانی
گرفته
خواهند شد.
این گزینه
با -separate
ناسازگار
(مانعة‌الجمع)
است.
در نسخه 3.12 اضافه شد.
- -pixel-function-arg
- تعیین یک
آرگومان
برای ارائه
به تابع
پیکسل، در
قالب <NAME>=<VALUE>.
با تکرار
این گزینه
می‌توان
چندین
آرگومان را
تعیین کرد.
در نسخه 3.12 اضافه شد.
- -allow_projection_difference
- هنگامی که این گزینه تعیین شود، این ابزار حتی اگر مجموعه‌داده‌های ورودی سیستم تصویر یکسانی نداشته باشند، یک VRT ایجاد می‌کند. توجه: این به این معنی نیست که آن‌ها بازتصویر (reproject) خواهند شد؛ سیستم تصویر آن‌ها صرفاً نادیده گرفته می‌شود.
- -a_srs <srs_def>
- بازنویسی سیستم تصویر برای فایل خروجی. مقدار <srs_def> می‌تواند هر یک از قالب‌های معمول GDAL/OGR، شامل WKT کامل، PROJ.4، EPSG:n یا فایلی حاوی WKT باشد. هیچ بازتصویری انجام نمی‌شود.
- -r {nearest|bilinear|cubic|cubicspline|lanczos|average|mode}
- انتخاب الگوریتم نمونه‌برداری مجدد (resampling). مقدار nearest پیش‌فرض است
- -oo <NAME>=<VALUE>
- گزینهٔ باز کردن مجموعه داده (وابسته به قالب)
- -co <NAME>=<VALUE>
- تعیین یک
گزینه
ایجاد
راه‌انداز
VRT.
در نسخه 3.10 اضافه شد.
- -input_file_list <filename>
- تعیین یک فایل متنی شامل نام یک فایل ورودی در هر سطر. مثال 2 را ببینید.
- -q
- غیرفعال کردن نوار پیشرفت در کنسول
- -overwrite
- رونویسی VRT در صورتی که از قبل وجود داشته باشد.
- -strict
- تبدیل
هشدارها به
خطا. این
گزینه با
-non_strict
ناسازگار
(مانعة‌الجمع)
است، که
دومی
پیش‌فرض
است.
در نسخه 3.4.2 اضافه شد.
- -non_strict
- صرف‌نظر
کردن از
مجموعه‌داده‌های
منبعی که
دارای
هشدار
هستند و
ادامهٔ
پردازش. این
حالت
پیش‌فرض
است.
در نسخه 3.4.2 اضافه شد.
- -write_absolute_path
- در نسخه 3.12.0
اضافه شد.
نوشتن مسیر مطلق مجموعه‌داده‌های ورودی را فعال می‌کند. به‌طور پیش‌فرض، نام فایل‌های ورودی در صورت امکان به‌صورت نسبی نسبت به نام فایل VRT نوشته می‌شوند.
مثال ۱: ساخت یک موزاییک مجازی از تمام فایل‌های TIFF موجود در یک دایرکتوری
gdalbuildvrt doq_index.vrt doq/*.tif
مثال ۲: ساخت یک موزاییک مجازی از فایل‌هایی که نام آن‌ها در یک فایل متنی مشخص شده است
gdalbuildvrt -input_file_list my_list.txt doq_index.vrt
مثال ۳: ساخت یک موزاییک مجازی RGB از ۳ فایل ورودی تک‌بانده
gdalbuildvrt -separate rgb.vrt red.tif green.tif blue.tif
مثال ۴: ساخت یک موزاییک مجازی با رنگ پس‌زمینه آبی (RGB: 0 0 255)
gdalbuildvrt -hidenodata -vrtnodata "0 0 255" doq_index.vrt doq/*.tif
وضعیت خروج (EXIT STATUS)
این برنامه در صورت موفقیت کد وضعیت ۰ و در صورت بروز خطا مقداری غیر صفر برمی‌گرداند (خطاهای غیرمسدودکننده که به‌صورت هشدار صادر می‌شوند، اجرای موفقیت‌آمیز در نظر گرفته خواهند شد).
رابط برنامه‌نویسی C (C API)
این ابزار همچنین از طریق C با GDALBuildVRT() قابل فراخوانی است.
نویسندگان (AUTHORS)
Even Rouault <even.rouault@spatialys.com>
کپی‌رایت و تکثیر (COPYRIGHT)
1998-2026
| August 18, 2026 |