.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "GDALBUILDVRT" "1" "Aug 18, 2026" "" "GDAL" .SH "نام (NAME)" gdalbuildvrt \- ساخت یک VRT از فهرستی از مجموعه‌داده‌ها. .SH "خلاصه دستور (SYNOPSIS)" .INDENT 0.0 .INDENT 3.5 .sp .EX gdalbuildvrt [\-\-help] [\-\-long\-usage] [\-\-help\-general] [\-\-quiet] [[\-strict]|[\-non_strict]] [\-tile_index ] [\-resolution user|average|common|highest|lowest|same] [\-tr ] [\-input_file_list ] [[\-separate]|[\-pixel\-function ]] [\-pixel\-function\-arg =]... [\-allow_projection_difference] [\-sd ] [\-tap] [\-te ] [\-addalpha] [\-b ]... [\-hidenodata] [\-overwrite] [\-srcnodata \(dq[ ]...\(dq] [\-vrtnodata \(dq[ ]...\(dq] [\-a_srs ] [\-r nearest|bilinear|cubic|cubicspline|lanczos|average|mode] [\-oo =]... [\-co =]... [\-ignore_srcmaskband] [\-nodata_max_mask_threshold ] []... .EE .UNINDENT .UNINDENT .SH "توضیحات (DESCRIPTION)" .sp این برنامه یک \fI\%VRT (Virtual Dataset)\fP رستری ایجاد می‌کند که موزاییکی از فهرستی از مجموعه‌داده‌های ورودی GDAL است. فهرست مجموعه‌داده‌های ورودی GDAL را می‌توان در انتهای خط فرمان مشخص کرد، برای فهرست‌های بسیار طولانی در یک فایل متنی (یک نام فایل در هر خط) قرار داد، یا می‌تواند یک tileindex در MapServer باشد (ابزار \fI\%gdaltindex\fP را ببینید). در صورت استفاده از نمایه کاشی، تمام ورودی‌های موجود در نمایه کاشی به VRT اضافه خواهند شد. .sp \fBنکته:\fP .INDENT 0.0 .INDENT 3.5 از نسخه GDAL 3.9 به بعد، برای موزاییک‌های مجازی با تعداد بسیار زیادی رستر منبع (صدها هزار رستر منبع یا بیشتر)، توصیه می‌شود از ابزار \fI\%gdaltindex\fP برای ایجاد یک نمایه کاشی سازگار با درایور \fI\%GTI\fP استفاده شود. .UNINDENT .UNINDENT .sp \fBنکته کاربردی:\fP .INDENT 0.0 .INDENT 3.5 معادل در رابط خط فرمان جدید \(dqgdal\(dq: .sp دستورات \fI\%gdal raster mosaic\fP و \fI\%gdal raster stack\fP را ببینید\&. .UNINDENT .UNINDENT .sp با گزینهٔ \fI\%\-separate\fP، هر ورودی در یک باند جداگانه در مجموعه‌دادهٔ VRT قرار می‌گیرد. در غیر این صورت، فایل‌ها به عنوان رسترهای منبعِ یک موزاییک بزرگ‌تر در نظر گرفته می‌شوند و فایل VRT همان تعداد باند فایل‌های ورودی را خواهد داشت. .sp اگر یک مجموعه‌دادهٔ GDAL از چندین زیرمجموعه‌داده (subdataset) تشکیل شده باشد و دارای 0 باند رستری باشد، همهٔ زیرمجموعه‌داده‌ها به جای خود مجموعه‌داده به VRT اضافه خواهند شد. .sp دستور \fBgdalbuildvrt\fP بررسی‌هایی انجام می‌دهد تا اطمینان حاصل کند همهٔ فایل‌هایی که در VRT نهایی قرار می‌گیرند دارای ویژگی‌های مشابهی هستند: تعداد باندها، سیستم تصویر، تفسیر رنگ و غیره. در غیر این صورت، فایل‌هایی که با ویژگی‌های مشترک مطابقت نداشته باشند نادیده گرفته می‌شوند مگر اینکه از گزینهٔ \fI\%\-strict\fP استفاده شود. (این موضوع تنها در حالت پیش‌فرض صادق است و هنگام استفاده از گزینهٔ \fI\%\-separate\fP اعمال نمی‌شود) .sp از نسخه GDAL 3.12 به بعد، می‌توان تابعی (مانند \fBmin\fP، \fBmean\fP، \fBmedian\fP) را مشخص کرد (\fI\%\-pixel\-function\fP) تا مقادیر پیکسل‌ها را از ورودی‌های دارای هم‌پوشانی محاسبه کند. اگر هیچ تابعی مشخص نشود، یا در نسخه‌های قدیمی‌تر، ترتیب فهرست ورودی برای تعیین اولویت استفاده می‌شود. فایل‌هایی که در انتهای فهرست قرار دارند، فایل‌هایی هستند که محتوا از آن‌ها واکشی خواهد شد. توجه داشته باشید که nodata برای واکشی احتمالی داده‌ها از مجموعه‌داده‌های با اولویت پایین‌تر در نظر گرفته می‌شود، اما در حال حاضر، کانال آلفا برای ترکیب آلفا (alpha compositing) در نظر گرفته نمی‌شود (بنابراین منبعی با alpha=0 که روی منبع دیگری قرار می‌گیرد، محتوای آن را بازنویسی خواهد کرد). این رفتار ممکن است در نسخه‌های بعدی تغییر کند. .INDENT 0.0 .TP .B \-\-help نمایش این پیام راهنما و خروج. .UNINDENT .INDENT 0.0 .TP .B \-\-help\-general نمایش پیام کوتاهی درباره نحوه استفاده از گزینه‌های عمومی خط فرمان GDAL و خروج. .UNINDENT .INDENT 0.0 .TP .B \-q, \-\-quiet عدم نمایش پیام‌های پیشرفت و سایر خروجی‌های غیرخطا. .UNINDENT .INDENT 0.0 .TP .B \-tileindex استفاده از مقدار مشخص‌شده به عنوان فیلد نمایهٔ کاشی، به جای مقدار پیش‌فرض که \(aqlocation\(aq است. .UNINDENT .INDENT 0.0 .TP .B \-resolution {highest|lowest|average|user|same} در صورتی که تفکیک‌پذیری (رزولوشن) همه فایل‌های ورودی یکسان نباشد، پرچم \fI\%\-resolution\fP به کاربر امکان می‌دهد نحوه محاسبه تفکیک‌پذیری خروجی را کنترل کند. .sp گزینهٔ \fIhighest\fP کوچک‌ترین مقادیر ابعاد پیکسل را در میان مجموعهٔ رسترهای منبع انتخاب می‌کند. .sp گزینهٔ \fIlowest\fP بزرگ‌ترین مقادیر ابعاد پیکسل را در میان مجموعهٔ رسترهای منبع انتخاب می‌کند. .sp گزینهٔ \fIaverage\fP حالت پیش‌فرض است و میانگین ابعاد پیکسل را در میان مجموعهٔ رسترهای منبع محاسبه می‌کند. .sp گزینهٔ \fIuser\fP باید در ترکیب با گزینهٔ \fI\%\-tr\fP برای مشخص کردن تفکیک‌پذیری هدف استفاده شود. .sp گزینهٔ \fIsame\fP (اضافه‌شده در GDAL 3.11) بررسی می‌کند که همه رسترهای منبع تفکیک‌پذیری یکسانی داشته باشند و در غیر این صورت با خطا خارج می‌شود. .sp گزینهٔ \fIcommon\fP (اضافه‌شده در GDAL 3.11) بزرگ‌ترین مقسوم‌علیه مشترک (ب.م.م) ابعاد پیکسل منبع را تعیین می‌کند، به عنوان مثال 0.2 برای ابعاد پیکسل منبع 0.4 و 0.6. .UNINDENT .INDENT 0.0 .TP .B \-tr تنظیم تفکیک‌پذیری هدف. مقادیر باید بر حسب واحدهای زمین‌مرجع بیان شوند. هر دو باید مقادیر مثبتی باشند. مشخص کردن این مقادیر مسلماً با مقادیر highest|lowest|average در گزینهٔ \fI\%\-resolution\fP ناسازگار است. .UNINDENT .INDENT 0.0 .TP .B \-tap (پیکسل‌های تراز شده با هدف یا target aligned pixels) مختصات محدودهٔ فایل خروجی را با مقادیر \fI\%\-tr\fP تراز می‌کند، به‌گونه‌ای که محدودهٔ تراز شده شامل حداقل محدوده باشد. تراز کردن به این معنی است که مقادیر xmin / resx، ymin / resy، xmax / resx و ymax / resy مقادیری صحیح باشند. .UNINDENT .INDENT 0.0 .TP .B \-te تنظیم محدوده‌های زمین‌مرجع شدهٔ فایل VRT. مقادیر باید بر حسب واحدهای زمین‌مرجع بیان شوند. در صورت عدم تعیین، محدودهٔ VRT حداقل کادر محصورکننده (bounding box) مجموعهٔ رسترهای منبع خواهد بود. پیکسل‌های درون محدودهٔ VRT که توسط یک رستر منبع پوشش داده نشده‌اند، به عنوان پیکسل‌های معتبر با مقدار صفر خوانده می‌شوند مگر اینکه یک مقدار NODATA با استفاده از \fI\%\-vrtnodata\fP مشخص شده باشد یا یک باند ماسک آلفا با \fI\%\-addalpha\fP اضافه شود\&. .UNINDENT .INDENT 0.0 .TP .B \-addalpha در صورتی که رستر منبع فاقد باند ماسک آلفا باشد، یک باند به VRT اضافه می‌کند. عمدتاً برای منابع RGB (یا منابع در مقیاس خاکستری) مفید است. باند آلفا در لحظه با مقدار 0 در نواحی فاقد رستر منبع، و با مقدار 255 در نواحی دارای رستر منبع پر می‌شود. اثر آن این است که یک نمایشگر RGBA، نواحی فاقد رستر منبع را شفاف و نواحی دارای رستر منبع را کدر رندر می‌کند. این گزینه با \fI\%\-separate\fP سازگار نیست\&. .UNINDENT .INDENT 0.0 .TP .B \-hidenodata حتی اگر هر باندی حاوی مقدار nodata باشد، ارائه این گزینه باعث می‌شود باند VRT مقدار NoData را گزارش نکند. زمانی که می‌خواهید رنگ پس‌زمینه مجموعه‌داده را کنترل کنید مفید است. با استفاده از این گزینه همراه با گزینهٔ \-addalpha، می‌توانید مجموعه‌داده‌ای آماده کنید که مقدار nodata را گزارش نمی‌کند اما در نواحی بدون داده شفاف است. .UNINDENT .INDENT 0.0 .TP .B \-srcnodata \(dq[ ]...\(dq تنظیم مقادیر nodata برای باندهای ورودی (می‌توان مقادیر متفاوتی برای هر باند ارائه کرد). اگر بیش از یک مقدار مشخص شود، همهٔ مقادیر باید در علامت نقل‌قول قرار گیرند تا به عنوان یک آرگومان واحد در سیستم‌عامل حفظ شوند. اگر این گزینه مشخص نشود، تنظیمات ذاتی nodata در مجموعه‌داده‌های منبع (در صورت وجود) استفاده خواهد شد. مقدار تعیین‌شده توسط این گزینه در عنصر NODATA از هر عنصر \fBComplexSource\fP نوشته می‌شود. برای نادیده گرفتن تنظیمات ذاتی nodata در مجموعه‌داده‌های منبع، از مقدار \fBNone\fP استفاده کنید. .UNINDENT .INDENT 0.0.TP .B \-ignore_srcmaskband در نسخه 3.3 اضافه شد. .sp از GDAL 3.3 به بعد، اگر یک منبع دارای یک باند ماسک (باند ماسک داخلی/خارجی، یا باند آلفا) باشد، به‌طور پیش‌فرض یک عنصر \fB\fP با عنصر فرزند \fBtrue\fP ایجاد می‌شود تا به راه‌انداز VRT دستور دهد از باند ماسک منبع برای ماسک کردن پیکسل‌های در حال ترکیب استفاده کند. این یک تعمیم از عنصر NODATA است. هنگام تعیین گزینهٔ \fI\%\-ignore_srcmaskband\fP، باند ماسک منابع در نظر گرفته نخواهد شد و در صورت هم‌پوشانی میان منابع، آخرین منبع بر منابع قبلی در نواحی هم‌پوشانی بازنویسی خواهد شد. .UNINDENT .INDENT 0.0 .TP .B \-nodata_max_mask_threshold در نسخه 3.9 اضافه شد. .sp یک منبع \fB\fP درج می‌کند که مقدار منبع را در صورتی که مقدار باند ماسک منبع کمتر یا مساوی آستانه باشد، با مقدار \fI\%\-vrtnodata\fP (یا 0 در صورت عدم تعیین) جایگزین می‌کند. این گزینه معمولاً برای تبدیل یک تصویر R,G,B,A به یک تصویر R,G,B با مقدار NoData استفاده می‌شود. .UNINDENT .INDENT 0.0 .TP .B \-b انتخاب یک ورودی برای پردازش. شماره‌گذاری باندها از 1 است. اگر باندهای ورودی تعیین نشوند، تمام باندها به VRT اضافه خواهند شد. می‌توان از چندین سوئیچ \fI\%\-b\fP برای انتخاب مجموعه‌ای از باندهای ورودی استفاده کرد. .UNINDENT .INDENT 0.0 .TP .B \-sd اگر مجموعه داده ورودی شامل چندین زیرمجموعه داده (subdataset) باشد، از زیرمجموعه داده با شماره تعیین‌شده (شروع از 1) استفاده می‌کند. این روش جایگزینی برای ارائه نام کامل زیرمجموعه داده به عنوان ورودی به ابزار است. .UNINDENT .INDENT 0.0 .TP .B \-vrtnodata \(dq[ ]...\(dq تنظیم مقادیر nodata در سطح باند VRT (می‌توان مقادیر متفاوتی را برای هر باند ارائه داد). اگر بیش از یک مقدار ارائه شود، همه مقادیر باید در علامت نقل‌قول قرار گیرند تا به عنوان یک آرگومان واحد در سیستم‌عامل حفظ شوند (\fI\%مثال 4\fP). اگر این گزینه مشخص نشود، از تنظیمات nodata ذاتی در اولین مجموعه داده (در صورت وجود) استفاده خواهد شد. مقدار تعیین‌شده با این گزینه در عنصر \fBNoDataValue\fP مربوط به هر \fBVRTRasterBand element\fP\& نوشته می‌شود. از مقدار \fINone\fP برای نادیده گرفتن تنظیمات nodata ذاتی در مجموعه‌داده‌های منبع استفاده کنید. .UNINDENT .INDENT 0.0 .TP .B \-separate قرار دادن هر فایل ورودی در یک باند جداگانه. \fI\%مثال 3\fP\& را ببینید. برخلاف حالت پیش‌فرض، نیازی نیست که همه باندها نوع داده یکسانی داشته باشند. این گزینه با \fI\%\-pixel\-function\fP\& ناسازگار (مانعة‌الجمع) است. .sp از GDAL 3.8 به بعد، تمام باندهای هر فایل ورودی به عنوان باندهای مجزای VRT اضافه می‌شوند، مگر اینکه \fI\%\-b\fP برای انتخاب زیرمجموعه‌ای از آن‌ها تعیین شده باشد. پیش از GDAL 3.8، فقط اولین باند هر فایل ورودی در یک باند جدید VRT قرار می‌گرفت و \fI\%\-b\fP نادیده گرفته می‌شد. .UNINDENT .INDENT 0.0 .TP .B \-pixel\-function تعیین نام یک تابع برای محاسبه مقدار از ورودی‌های دارای هم‌پوشانی. برای مشاهده فهرستی از توابع پیکسل موجود، به \fI\%Built\-in Pixel Functions\fP\& مراجعه کنید. اگر هیچ تابعی تعیین نشود، مقادیر از آخرین ورودی دارای هم‌پوشانی گرفته خواهند شد. این گزینه با \fI\%\-separate\fP\& ناسازگار (مانعة‌الجمع) است. .sp در نسخه 3.12 اضافه شد. .UNINDENT .INDENT 0.0 .TP .B \-pixel\-function\-arg تعیین یک آرگومان برای ارائه به تابع پیکسل، در قالب \fB=\fP\&. با تکرار این گزینه می‌توان چندین آرگومان را تعیین کرد. .sp در نسخه 3.12 اضافه شد. .UNINDENT .INDENT 0.0 .TP .B \-allow_projection_difference هنگامی که این گزینه تعیین شود، این ابزار حتی اگر مجموعه‌داده‌های ورودی سیستم تصویر یکسانی نداشته باشند، یک VRT ایجاد می‌کند. توجه: این به این معنی نیست که آن‌ها بازتصویر (reproject) خواهند شد؛ سیستم تصویر آن‌ها صرفاً نادیده گرفته می‌شود. .UNINDENT .INDENT 0.0 .TP .B \-a_srs بازنویسی سیستم تصویر برای فایل خروجی. مقدار می‌تواند هر یک از قالب‌های معمول GDAL/OGR، شامل WKT کامل، PROJ.4، EPSG:n یا فایلی حاوی WKT باشد. هیچ بازتصویری انجام نمی‌شود. .UNINDENT .INDENT 0.0 .TP .B \-r {nearest|bilinear|cubic|cubicspline|lanczos|average|mode} انتخاب الگوریتم نمونه‌برداری مجدد (resampling). مقدار nearest پیش‌فرض است .UNINDENT .INDENT 0.0 .TP .B \-oo = گزینهٔ باز کردن مجموعه داده (وابسته به قالب) .UNINDENT .INDENT 0.0 .TP .B \-co = تعیین یک \fI\%گزینه ایجاد راه‌انداز VRT\fP\&. .sp در نسخه 3.10 اضافه شد. .UNINDENT .INDENT 0.0 .TP .B \-input_file_list تعیین یک فایل متنی شامل نام یک فایل ورودی در هر سطر. \fI\%مثال 2\fP\& را ببینید. .UNINDENT .INDENT 0.0 .TP .B \-q غیرفعال کردن نوار پیشرفت در کنسول .UNINDENT .INDENT 0.0 .TP .B \-overwrite رونویسی VRT در صورتی که از قبل وجود داشته باشد. .UNINDENT .INDENT 0.0 .TP .B \-strict تبدیل هشدارها به خطا. این گزینه با \fI\%\-non_strict\fP ناسازگار (مانعة‌الجمع) است، که دومی پیش‌فرض است. .sp در نسخه 3.4.2 اضافه شد. .UNINDENT .INDENT 0.0 .TP .B \-non_strict صرف‌نظر کردن از مجموعه‌داده‌های منبعی که دارای هشدار هستند و ادامهٔ پردازش. این حالت پیش‌فرض است. .sp در نسخه 3.4.2 اضافه شد. .UNINDENT .INDENT 0.0 .TP .B \-write_absolute_path در نسخه 3.12.0 اضافه شد. .sp نوشتن مسیر مطلق مجموعه‌داده‌های ورودی را فعال می‌کند. به‌طور پیش‌فرض، نام فایل‌های ورودی در صورت امکان به‌صورت نسبی نسبت به نام فایل VRT نوشته می‌شوند. .UNINDENT.SH "مثال‌ها (EXAMPLES)" .SS مثال ۱: ساخت یک موزاییک مجازی از تمام فایل‌های TIFF موجود در یک دایرکتوری .INDENT 0.0 .INDENT 3.5 .sp .EX gdalbuildvrt doq_index.vrt doq/*.tif .EE .UNINDENT .UNINDENT .SS مثال ۲: ساخت یک موزاییک مجازی از فایل‌هایی که نام آن‌ها در یک فایل متنی مشخص شده است .INDENT 0.0 .INDENT 3.5 .sp .EX gdalbuildvrt \-input_file_list my_list.txt doq_index.vrt .EE .UNINDENT .UNINDENT .SS مثال ۳: ساخت یک موزاییک مجازی RGB از ۳ فایل ورودی تک‌بانده .INDENT 0.0 .INDENT 3.5 .sp .EX gdalbuildvrt \-separate rgb.vrt red.tif green.tif blue.tif .EE .UNINDENT .UNINDENT .SS مثال ۴: ساخت یک موزاییک مجازی با رنگ پس‌زمینه آبی (RGB: 0 0 255) .INDENT 0.0 .INDENT 3.5 .sp .EX gdalbuildvrt \-hidenodata \-vrtnodata \(dq0 0 255\(dq doq_index.vrt doq/*.tif .EE .UNINDENT .UNINDENT .SH "وضعیت خروج (EXIT STATUS)" .sp این برنامه در صورت موفقیت کد وضعیت ۰ و در صورت بروز خطا مقداری غیر صفر برمی‌گرداند (خطاهای غیرمسدودکننده که به‌صورت هشدار صادر می‌شوند، اجرای موفقیت‌آمیز در نظر گرفته خواهند شد). .SH "رابط برنامه‌نویسی C (C API)" .sp این ابزار همچنین از طریق C با \fI\%GDALBuildVRT()\fP\& قابل فراخوانی است. .SH "نویسندگان (AUTHORS)" Even Rouault .SH "کپی‌رایت و تکثیر (COPYRIGHT)" 1998-2026 .\" Generated by docutils manpage writer. .