GDALADDO(1) GDAL GDALADDO(1)

gdaladdo - ساخت یا بازسازی تصاویر بازبینی (overview).

Usage: gdaladdo [--help] [--long-usage] [--help-general]
                [-r nearest|average|rms|gauss|bilinear|cubic|cubicspline|lanczos|average_magphase|mode]
                [-ro] [--quiet] [-b <band>]... [-oo <NAME=VALUE>]...
                [-minsize <val>]
                [[-clean]|[--partial-refresh-from-source-timestamp]|
                [--partial-refresh-from-projwin <ulx> <uly> <lrx> <lry>]|
                [--partial-refresh-from-source-extent <filename1>[,<filenameN>]...]]
                filename [<level>]...

ابزار gdaladdo می‌تواند برای ساخت یا بازسازی تصاویر بازبینی (overview) برای بیشتر قالب‌های پرونده پشتیبانی‌شده با استفاده از یکی از چندین الگوریتم زیرنمونه‌گیری (downsampling) به کار رود.

نکته:

معادل در رابط خط فرمان جدید "gdal":

ببینید gdal raster overview add، gdal raster overview delete و gdal raster overview refresh.

نمایش این پیام راهنما و خروج.
--help-general
نمایش یک پیام کاربردی کوتاه برای گزینه‌های عمومی خط فرمان GDAL و خروج.
عدم نمایش پیام‌های پیشرفت و سایر خروجی‌های غیرخطا.
انتخاب الگوریتم بازنمونه‌گیری (resampling). مقدار پیش‌فرض nearest است که در صورت نیاز به دقت زیرپیکسلی (sub-pixel) معمولاً مناسب نیست.

از نسخه GDAL 3.9 به بعد، هنگام تازه‌سازی بازبینی‌های موجود TIFF، در صورتی که -r مشخص نشده باشد، از روشی که پیش‌تر استفاده شده بود (مطابق با متادیتای RESAMPLING در بازبینی) استفاده خواهد شد.

روش‌های موجود عبارتند از:

nearest بازنمونه‌گیر نزدیک‌ترین همسایه (نمونه‌برداری ساده) را اعمال می‌کند.

average میانگین تمام پیکسل‌های سهیم غیر NODATA را محاسبه می‌کند. از GDAL 3.1 به بعد، این یک میانگین وزنی است که وزن پیکسل‌های مبدأ را که به طور کامل در پیکسل هدف سهیم نیستند به درستی در نظر می‌گیرد.

rms جذر میانگین مربعات / میانگین درجه دو تمام پیکسل‌های سهیم غیر NODATA را محاسبه می‌کند (GDAL >= 3.3).

gauss قبل از محاسبه بازبینی، یک هسته گاوسی (Gaussian kernel) اعمال می‌کند که می‌تواند به نتایج بهتری نسبت به میانگین‌گیری ساده منجر شود، مانند موارد لبه‌های تیز با کنتراست بالا یا الگوهای نویزدار. مقادیر سطح پیشنهادی باید ۲، ۴، ۸ و... باشند تا یک هسته بازنمونه‌گیری گاوسی ۳x۳ انتخاب شود.

bilinear یک هسته پیچش دوخطی (bilinear convolution) اعمال می‌کند.

cubic یک هسته پیچش مکعبی (cubic convolution) اعمال می‌کند.

cubicspline یک هسته پیچش B-Spline اعمال می‌کند.

lanczos یک هسته پیچش سینک پنجره‌بندی‌شده لنتسوش (Lanczos windowed sinc) اعمال می‌کند.

average_magphase داده‌های مختلط را در فضای اندازه/فاز (mag/phase) میانگین‌گیری می‌کند.

mode مقداری را انتخاب می‌کند که بیشترین تکرار را در میان تمام نقاط نمونه‌برداری شده دارد.

انتخاب یک باند ورودی band برای ایجاد بازبینی. شماره‌گذاری باندها از ۱ آغاز می‌شود. می‌توان چندین سوئیچ -b را برای انتخاب مجموعه‌ای از باندهای ورودی جهت تولید بازبینی به کار برد.
باز کردن مجموعه داده در حالت فقط‌خواندنی، به منظور تولید بازبینی خارجی (به‌ویژه برای GeoTIFF).
حذف تمام بازبینی‌ها.
گزینه باز کردن مجموعه داده (وابسته به قالب).
حداکثر پهنا یا ارتفاع کوچک‌ترین سطح بازبینی. تنها زمانی در نظر گرفته می‌شود که سطوح صریح مشخص نشده باشند. مقدار پیش‌فرض ۲۵۶ است.
اضافه‌شده در نسخه 3.8.

این گزینه تازه‌سازی جزئی بازبینی‌های موجود را انجام می‌دهد، هنگامی که <filename> یک پرونده VRT با بازبینی خارجی باشد. این گزینه برچسب زمانی تغییر (timestamp) تمام منابع VRT را بررسی می‌کند و بازبینی را برای مناطقی که منبع آن‌ها دارای برچسب زمانی تازه‌تر از بازبینی خارجی VRT است، بازتولید می‌کند. به طور پیش‌فرض تمام سطوح بازبینی موجود تازه‌سازی خواهند شد، مگر اینکه سطوح صریح مشخص شوند. به مثال ۷ مراجعه کنید.

اضافه‌شده در نسخه 3.8.

این گزینه تازه‌سازی جزئی بازبینی‌های موجود را در ناحیه مورد نظر مشخص‌شده با مختصات زمین‌مرجع انجام می‌دهد که در آن <ulx> مقدار X گوشه بالا-چپ، <uly> مقدار Y گوشه بالا-چپ، <lrx> مقدار X گوشه پایین-راست و <lry> مقدار Y گوشه پایین-راست است. به طور پیش‌فرض تمام سطوح بازبینی موجود تازه‌سازی خواهند شد، مگر اینکه سطوح صریح مشخص شوند.

اضافه‌شده در نسخه 3.8.

این گزینه تازه‌سازی جزئی بازبینی‌های موجود را در ناحیه مورد نظر مشخص‌شده توسط یک یا چند نام پرونده (نام‌ها با کاما جدا می‌شوند) انجام می‌دهد. توجه داشته باشید که نام پرونده‌ها تنها برای تعیین مناطق مورد نظر جهت تازه‌سازی استفاده می‌شوند. پیکسل‌های منبع مرجع، همان پیکسل‌های مجموعه داده اصلی هستند. به طور پیش‌فرض تمام سطوح بازبینی موجود تازه‌سازی خواهند شد، مگر اینکه سطوح صریح مشخص شوند. به مثال ۸ مراجعه کنید.

<filename>
پرونده‌ای که قرار است بازبینی‌ها برای آن ساخته شوند (یا بازبینی‌های آن حذف شوند).
<levels>
فهرستی از سطوح صحیح بازبینی برای ساخت. با گزینه -clean نادیده گرفته می‌شود.
سطوح دیگر برای ساخت بازبینی‌ها الزامی نیستند. در این حالت، ضرایب توان دو بازبینی مناسب انتخاب خواهند شد تا زمانی که کوچک‌ترین بازبینی از مقدار سوئیچ -minsize کوچک‌تر شود.

از نسخه GDAL 3.9 به بعد، در صورت وجود بازبینی‌های قبلی، اگر سطوح صریحی تعیین نشده باشد، از سطوح متناظر برای تازه‌سازی آن‌ها استفاده خواهد شد.

ابزار gdaladdo تاپل‌های NODATA_VALUES (متادیتای ویژه مجموعه داده) را به درستی رعایت می‌کند به طوری که فقط یک سه‌تایی RGB مشخص (در مورد تصویر RGB) به عنوان مقدار nodata در نظر گرفته می‌شود، نه هر مقدار از سه‌تایی به صورت مستقل در هر باند.

انتخاب مقدار سطحی مانند 2 باعث می‌شود یک سطح بازبینی با نصف تفکیک‌پذیری (رزولوشن) لایه پایه (در هر بعد) محاسبه شود. اگر پرونده دارای سطوح بازبینی موجود در سطح انتخاب‌شده باشد، آن سطوح مجدداً محاسبه شده و درجا بازنویسی می‌شوند.

برای بازبینی‌های داخلی GeoTIFF (یا بازبینی‌های خارجی در قالب GeoTIFF)، توجه داشته باشید که -clean اندازه پرونده را کاهش نمی‌دهد. اجرای بعدی gdaladdo با سطوح بازبینی باعث گسترش پرونده می‌شود، به جای اینکه از فضای بازبینی‌های حذف‌شده قبلی استفاده مجدد کند. اگر فقط می‌خواهید روش بازنمونه‌گیری را روی پرونده‌ای که قبلاً بازبینی‌های آن محاسبه شده است تغییر دهید، نیازی به پاکسازی بازبینی‌های موجود ندارید.

برخی از درایورهای قالب اصلاً از بازبینی پشتیبانی نمی‌کنند. بسیاری از درایورهای قالب، بازبینی‌ها را در یک پرونده ثانویه با پسوند .ovr که در واقع در قالب TIFF است ذخیره می‌کنند. به طور پیش‌فرض، درایور GeoTIFF بازبینی‌ها را درون خود پرونده مورد نظر ذخیره می‌کند (اگر قابل نوشتن باشد)، مگر اینکه پرچم -ro مشخص شده باشد.

بیشتر درایورها از قالب بازبینی جایگزین با استفاده از قالب Erdas Imagine نیز پشتیبانی می‌کنند. برای فعال‌سازی این قابلیت، از گزینه پیکربندی USE_RRD=YES استفاده کنید (مثال ۵). این کار بازبینی‌ها را در یک پرونده مرتبط .aux قرار می‌دهد که برای استفاده مستقیم در Imagine یا ArcGIS و همچنین برنامه‌های GDAL مناسب است (مانند --config USE_RRD YES).

بازبینی‌های خارجی ساخته‌شده در قالب TIFF را می‌توان با استفاده از گزینه پیکربندی COMPRESS_OVERVIEW فشرده‌سازی کرد. تمام روش‌های فشرده‌سازی که توسط درایور GeoTIFF پشتیبانی می‌شوند در اینجا نیز در دسترس هستند (مانند --config COMPRESS_OVERVIEW DEFLATE). تفسیر نورسنجی (photometric interpretation) را می‌توان با گزینه پیکربندی PHOTOMETRIC_OVERVIEW=RGB/YCBCR/... و درهم‌بافی (interleaving) را با گزینه پیکربندی INTERLEAVE_OVERVIEW=PIXEL/BAND تنظیم کرد.

از GDAL 3.6 به بعد، COMPRESS_OVERVIEW و INTERLEAVE_OVERVIEW هنگام ایجاد بازبینی‌های داخلی برای پرونده‌های TIFF رعایت می‌شوند.

برای بازبینی‌های فشرده‌شده با JPEG (خارجی و داخلی)، کیفیت JPEG را می‌توان با --config JPEG_QUALITY_OVERVIEW value تنظیم کرد.

برای بازبینی‌های فشرده‌شده با WEBP (خارجی و داخلی)، سطح کیفیت WEBP را می‌توان با --config WEBP_LEVEL_OVERVIEW value تنظیم کرد. در صورت عدم تنظیم، مقدار پیش‌فرض ۷۵ خواهد بود.

برای بازبینی‌های فشرده‌شده با WEBP (خارجی و داخلی)، سوئیچ بدون‌اتلاف/با‌اتلاف (lossless/lossy) را می‌توان با --config WEBP_LOSSLESS_OVERVIEW value تنظیم کرد. در صورت عدم تنظیم، مقدار پیش‌فرض NO (با‌اتلاف) خواهد بود. اضافه‌شده در GDAL 3.6.0.

برای بازبینی‌های فشرده‌شده با LERC (خارجی و داخلی)، آستانه حداکثر خطا را می‌توان با --config MAX_Z_ERROR_OVERVIEW value تنظیم کرد. در صورت عدم تنظیم، مقدار پیش‌فرض ۰ (بدون‌اتلاف) خواهد بود. اضافه‌شده در GDAL 3.4.1.

برای بازبینی‌های فشرده‌شده با DEFLATE یا LERC_DEFLATE (خارجی و داخلی)، سطح فشرده‌سازی را می‌توان با --config ZLEVEL_OVERVIEW value تنظیم کرد. در صورت عدم تنظیم، مقدار پیش‌فرض ۶ خواهد بود. اضافه‌شده در GDAL 3.4.1.

برای بازبینی‌های فشرده‌شده با ZSTD یا LERC_ZSTD (خارجی و داخلی)، سطح فشرده‌سازی را می‌توان با --config ZSTD_LEVEL_OVERVIEW value تنظیم کرد. در صورت عدم تنظیم، مقدار پیش‌فرض ۹ خواهد بود. اضافه‌شده در GDAL 3.4.1.

برای بازبینی‌های فشرده‌شده با JPEG-XL (خارجی و داخلی)، تنظیمات زیر از GDAL 3.9.0 در دسترس هستند:

  • اینکه فشرده‌سازی بدون‌اتلاف باشد یا خیر با --config JXL_LOSSLESS_OVERVIEW YES|NO. مقدار پیش‌فرض YES است.
  • سطح تلاش با --config JXL_EFFORT_OVERVIEW value، با مقداری بین ۱ (سریع) و ۹ (آهسته/دقیق). مقدار پیش‌فرض ۵ است.
  • سطح فاصله برای فشرده‌سازی با‌اتلاف با --config JXL_DISTANCE_OVERVIEW value، با مقدار: 0=از نظر ریاضی بدون‌اتلاف، 1.0=از نظر بصری بدون‌اتلاف، محدوده معمول [0.5,3]. مقدار پیش‌فرض 1.0 است. در صورتی که JXL_LOSSLESS_OVERVIEW برابر YES باشد نادیده گرفته می‌شود.
  • سطح فاصله برای فشرده‌سازی با‌اتلاف کانال آلفا با --config JXL_ALPHA_DISTANCE_OVERVIEW value، با مقدار: 0=از نظر ریاضی بدون‌اتلاف، 1.0=از نظر بصری بدون‌اتلاف، محدوده معمول [0.5,3]. مقدار پیش‌فرض همان مقدار JXL_DISTANCE_OVERVIEW است. در صورتی که JXL_LOSSLESS_OVERVIEW برابر YES باشد نادیده گرفته می‌شود.

برای بازبینی‌های خارجی فشرده‌شده با LZW، ZSTD یا DEFLATE، مقدار پیش‌بین (predictor) را می‌توان با --config PREDICTOR_OVERVIEW 1|2|3 تنظیم کرد.

برای تولید کوچک‌ترین بازبینی‌های ممکن JPEG-In-TIFF، باید از موارد زیر استفاده کنید:

--config COMPRESS_OVERVIEW JPEG --config PHOTOMETRIC_OVERVIEW YCBCR --config INTERLEAVE_OVERVIEW PIXEL

بازبینی‌های خارجی را می‌توان با استفاده از گزینه پیکربندی BIGTIFF_OVERVIEW در قالب BigTIFF ایجاد کرد: --config BIGTIFF_OVERVIEW {IF_NEEDED|IF_SAFER|YES|NO}.

مقدار پیش‌فرض IF_SAFER است. رفتار این گزینه دقیقاً همانند گزینه ایجاد BIGTIFF است که در مستندات درایور GeoTIFF آمده است.

  • مقدار YES ساخت BigTIFF را اجباری می‌کند.
  • مقدار NO ساخت TIFF کلاسیک را اجباری می‌کند.
  • مقدار IF_NEEDED تنها در صورتی BigTIFF می‌سازد که به وضوح نیاز باشد (فشرده‌نشده، و بازبینی‌های بزرگ‌تر از ۴ گیگابایت).
  • مقدار IF_SAFER در صورتی که پرونده حاصل احتمالاً از ۴ گیگابایت فراتر رود، BigTIFF می‌سازد.

پرونده‌های بازبینی خلوت (sparse) GeoTIFF (یعنی کاشی‌هایی که در صورت بودن همه پیکسل‌هایشان در مقدار nodata یا ۰ حذف می‌شوند) را می‌توان با --config SPARSE_OK_OVERVIEW ON به دست آورد. اضافه‌شده در GDAL 3.4.1.

برای توضیحات بیشتر درباره همه این گزینه‌ها، مستندات درایور قالب پرونده GTiff -- GeoTIFF را ببینید.

--config GDAL_TIFF_OVR_BLOCKSIZE <size>

مثال: --config GDAL_TIFF_OVR_BLOCKSIZE 256

مقدار پیش‌فرض ۱۲۸ است، یا از GDAL 3.1 به بعد، هنگام ساخت بازبینی‌ها روی یک پرونده کاشی‌بندی‌شده GeoTIFF، اندازه کاشی تصویر با تفکیک‌پذیری کامل خواهد بود. نکته: بدون این تنظیم، پرونده می‌تواند تصویری با تفکیک‌پذیری کامل با اندازه بلوکی متفاوت از اندازه بلوک بازبینی‌ها داشته باشد (مثلاً تصویر تفکیک‌پذیری کامل با اندازه بلوک ۲۵۶ و بازبینی‌ها با اندازه بلوک ۱۲۸).

مقادیر نامعتبر در پیکسل‌های منبع، که از طریق متادیتای مقدار nodata تنظیم‌شده روی باند مبدأ، یک باند ماسک، یا یک باند آلفا شناسایی می‌شوند، در حین بازنمونه‌گیری استفاده نخواهند شد.

جزئیات نحوه در نظر گرفتن آن به هسته بازنمونه‌گیری بستگی دارد:

  • برای بازنمونه‌گیری nearest، برای هر پیکسل هدف، یکی از پیکسل‌های منبع سهیم بالقوه (به روش خاص پیاده‌سازی) انتخاب می‌شود. مقدار آن همان‌طور که هست استفاده می‌شود، چه معتبر باشد و چه نامعتبر.
  • برای bilinear، cubic، cubicspline و lanczos، برای هر پیکسل هدف، وزن پیکسل‌های منبع سهیم روی صفر تنظیم می‌شود تا هنگام ماسک بودن نادیده گرفته شوند. یک ویژگی اضافی برای cubic و lanczos وجود دارد: با توجه به اینکه برخی از وزن‌ها در هسته منفی هستند، چنین رویکردی می‌تواند در هنگام تناوب پیکسل‌های معتبر و نامعتبر منجر به فراجهش/فروجهش (overshoot/undershoot) شدید شود. در نتیجه، در هر یک از جهات افقی یا عمودی، اگر حداکثر تعداد پیکسل‌های معتبر منبع در هر بعد کمتر از شعاع هسته بازنمونه‌گیری باشد، پیکسل هدف به عنوان nodata در نظر گرفته می‌شود.
  • برای سایر روش‌های بازنمونه‌گیری، پیکسل‌های منبع سهیم در پیکسل هدف در صورت ماسک بودن نادیده گرفته می‌شوند. فقط موارد معتبر در نظر گرفته می‌شوند. در صورت عدم وجود، پیکسل هدف به عنوان nodata در نظر گرفته می‌شود.

اضافه‌شده در نسخه 3.2.

گزینه پیکربندی GDAL_NUM_THREADS را می‌توان روی ALL_CPUS یا یک مقدار صحیح تنظیم کرد تا تعداد ریسمان‌های مورد استفاده برای محاسبه بازبینی مشخص شود.

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

قابلیت‌های این ابزار را می‌توان از طریق C با تابع GDALBuildOverviews() اجرا کرد.

gdaladdo -r average abc.tif

gdaladdo -r average abc.tif 2 4 8 16

gdaladdo -ro --config COMPRESS_OVERVIEW=YES erdas.img 2 4 8 16

اگر مجموعه داده یک GeoTIFF قابل نوشتن باشد، برای اجبار به تولید بازبینی خارجی، باید گزینه -ro را نیز اضافه کنید.

gdaladdo --config COMPRESS_OVERVIEW=JPEG --config PHOTOMETRIC_OVERVIEW=YCBCR
         --config INTERLEAVE_OVERVIEW=PIXEL rgb_dataset.ext 2 4 8 16

gdaladdo --config USE_RRD=YES airphoto.jpg 3 9 27 81

به عنوان مثال، یکی از احتمالاً چندین لایه رستر در یک GeoPackage (پارامتر "filename" باید شامل پیشوند درایور، نام پرونده و نام زیرمجموعه داده باشد، مانند آنچه توسط gdalinfo نشان داده می‌شود):

gdaladdo GPKG:file.gpkg:layer

این کار زمانی لازم است که منابع پس از تولید .vrt.ovr تغییر کرده باشند:

gdalbuildvrt my.vrt tile1.tif tile2.tif                          # create VRT
gdaladdo -r cubic my.vrt                                         # initial overview generation
touch tile1.tif                                                  # simulate update of one of the source tiles
gdaladdo --partial-refresh-from-source-timestamp -r cubic my.vrt # refresh overviews

gdalwarp -overwrite tile1.tif tile2.tif mosaic.tif                          # create mosaic
gdaladdo -r cubic mosaic.tif                                                # initial overview generation
touch tile1.tif                                                             # simulate update of one of the source tiles
gdalwarp tile1.tif mosaic.tif                                               # update mosaic
gdaladdo --partial-refresh-from-source-extent tile1.tif -r cubic mosaic.tif # refresh overviews

Frank Warmerdam <warmerdam@pobox.com>, Silke Reimer <silke@intevation.de>

1998-2026

August 18, 2026