GDAL-RASTER-OVERVIEW-REFRESH(1)      GDAL      GDAL-RASTER-OVERVIEW-REFRESH(1)

نام (NAME)
       gdal-raster-overview-refresh - تازه‌سازی پیش‌نمایش‌ها

       در نسخه 3.12 اضافه شد.


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

          Usage: gdal raster overview refresh [OPTIONS] <INPUT>

          Refresh overviews.

          Positional arguments:
            -i, --dataset, --input <INPUT>     Dataset (to be updated in-place, unless --external) [required]

          Common Options:
            -h, --help                         Display help message and exit
            --json-usage                       Display usage as JSON document and exit
            --config <KEY>=<VALUE>             Configuration option [may be repeated]
            -q, --quiet                        Quiet mode (no progress bar or warning message) [not available in pipelines]

          Options:
            --external                         Refresh external overviews
            -r, --resampling <RESAMPLING>      Resampling method. RESAMPLING=nearest|average|cubic|cubicspline|lanczos|bilinear|gauss|average_magphase|rms|mode
            --levels <LEVELS>                  Levels / decimation factors [may be repeated]
            --bbox <BBOX>                      Bounding box to refresh
                                               Mutually exclusive with --like, --use-source-timestamp
            --like <LIKE>                      Use extent of dataset(s) [may be repeated]
                                               Mutually exclusive with --bbox, --use-source-timestamp
            --use-source-timestamp             Use timestamp of VRT or GTI sources as refresh criterion
                                               Mutually exclusive with --bbox, --like

          Advanced Options:
            --oo, --open-option <KEY>=<VALUE>  Open options [may be repeated]

توضیحات (DESCRIPTION)
       دستور gdal raster overview refresh می‌تواند برای تازه‌سازی پیش‌نمایش‌های
       موجود یک مجموعه داده (dataset) به کار رود.  به‌طور پیش‌فرض تمام
       پیش‌نمایش‌ها تازه‌سازی می‌شوند، اما محدود کردن پیش‌نمایش‌های تازه‌سازی‌شده بر
       اساس سطح (level) و/یا محدوده (extent) نیز امکان‌پذیر است.

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

       --bbox <xmin>,<ymin>,<xmax>,ymax>
              این گزینه یک تازه‌سازی جزئی روی پیش‌نمایش‌های موجود، در ناحیه مورد
              نظر مشخص‌شده با مختصات زمین‌مرجع و بر حسب واحدهای CRS انجام می‌دهد.

              مقدار 'x' نشان‌دهنده مقادیر طول جغرافیایی برای CRS جغرافیایی و
              مؤلفه شرقی (easting) برای CRS تصویرشده است.  مقدار 'y' نشان‌دهنده
              مقادیر عرض جغرافیایی برای CRS جغرافیایی و مؤلفه شمالی (northing)
              برای CRS تصویرشده است.

       --dataset <DATASET>
              نام مجموعه داده که به‌طور پیش‌فرض در جای خود به‌روزرسانی می‌شود (مگر
              اینکه --external مشخص شده باشد). الزامی است.

       --external
              تازه‌سازی پیش‌نمایش‌های خارجی .ovr.

       --levels <level1,level2,...>
              فهرستی از سطوح پیش‌نمایش برای ساخت. هر سطح پیش‌نمایش باید یک مقدار
              عدد صحیح بزرگ‌تر یا مساوی ۲ باشد.

              در صورت مشخص نشدن، تمام پیش‌نمایش‌های موجود تازه‌سازی می‌شوند.

       --like <filename1>[,<filenameN>]...
              این گزینه یک تازه‌سازی جزئی روی پیش‌نمایش‌های موجود، در ناحیه مورد
              نظر مشخص‌شده توسط یک یا چند نام فایل (نام‌ها با ویرگول جدا می‌شوند)
              انجام می‌دهد.  توجه داشته باشید که نام فایل‌ها تنها برای تعیین
              نواحی مورد نظر جهت تازه‌سازی استفاده می‌شوند. پیکسل‌های منبع مرجع،
              همان پیکسل‌های مجموعه داده اصلی هستند.  به‌طور پیش‌فرض تمام سطوح
              پیش‌نمایش موجود تازه‌سازی خواهند شد، مگر اینکه سطوح به‌طور صریح
              مشخص شده باشند. به مثال ۲ مراجعه کنید.

       -r, --resampling
       {nearest|average|cubic|cubicspline|lanczos|bilinear|gauss|average_magphase|rms|mode}
              انتخاب یک الگوریتم بازنمونه‌برداری (resampling). مقدار پیش‌فرض
              nearest است که در صورت نیاز به دقت زیرپیکسل معمولاً مناسب نیست.

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

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

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

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

              روش bilinear یک هسته کانولوشن دوخطی را اعمال می‌کند.

              روش cubic یک هسته کانولوشن مکعبی را اعمال می‌کند.

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

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

              روش gauss پیش از محاسبه پیش‌نمایش یک هسته گاوسی اعمال می‌کند که
              می‌تواند به نتایج بهتری نسبت به میانگین‌گیری ساده منجر شود؛ مثلاً
              در مواردی با لبه‌های تیز و کنتراست بالا یا الگوهای نویزدار.
              مقادیر سطوح توصیه‌شده ۲، ۴، ۸ و... هستند تا یک هسته
              بازنمونه‌برداری گاوسی ۳×۳ انتخاب شود.

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

              روش rms مقدار جذر میانگین مربعات / میانگین مربعی تمام پیکسل‌های
              مشارکت‌کننده غیر NODATA را محاسبه می‌کند.

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

       --use-source-timestamp
              این گزینه یک تازه‌سازی جزئی روی پیش‌نمایش‌های موجود یک فایل VRT --
              GDAL Virtual Format یا GTI -- GDAL Raster Tile Index دارای
              پیش‌نمایش خارجی انجام می‌دهد.  این گزینه برچسب زمانی تغییرات
              (timestamp) تمام منابع VRT را بررسی می‌کند و پیش‌نمایش را برای
              نواحی مربوط به منابعی که برچسب زمانی آن‌ها تازه‌تر از پیش‌نمایش
              خارجی VRT است، دوباره تولید می‌نماید.  به‌طور پیش‌فرض تمام سطوح
              پیش‌نمایش موجود تازه‌سازی خواهند شد، مگر اینکه سطوح به‌طور صریح
              مشخص شده باشند. به مثال ۱ مراجعه کنید.

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

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

              ممکن است تکرار شود.

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

مثال‌ها (EXAMPLES)
   مثال ۱: تازه‌سازی پیش‌نمایش‌های خارجی یک فایل VRT با استفاده از برچسب زمانی
       فایل‌های منبع
       این کار زمانی نیاز است که فایل‌های منبع پس از ایجاد vrt.ovr. دستخوش
       تغییر شده باشند:

          gdal raster mosaic tile1.tif tile2.tif my.vrt               # create VRT
          gdal raster overview add --external -r cubic my.vrt         # initial overview generation
          touch tile1.tif                                             # simulate update of one of the source tiles
          gdal raster overview refresh --external -r cubic \
                                    --use-source-timestamp my.vrt     # refresh overviews

   مثال ۲: تازه‌سازی پیش‌نمایش‌های (داخلی) یک فایل TIFF

          gdal raster mosaic tile1.tif tile2.tif mosaic.tif       # create mosaic
          gdal raster overview add -r cubic mosaic.tif            # initial overview generation
          gdalwarp tile1_modif.tif mosaic.tif                     # update mosaic
          gdal raster overview refresh --like=tile1.tif my.tif    # refresh overviews

نویسندگان (AUTHORS)
       Even Rouault <even.rouault@spatialys.com>

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

                                August 18, 2026
                                               GDAL-RASTER-OVERVIEW-REFRESH(1)