نام (NAME)

gdal-raster-overview-add - افزودن نمای کلی (overview) به مجموعه‌داده رَستری

افزوده‌شده در نسخه 3.11.

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

Usage: gdal raster overview add [OPTIONS] <INPUT>
Adding 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:
  --overview-src <OVERVIEW-SRC>          Source overview dataset [may be repeated]
                                         Mutually exclusive with --levels
  --external                             Add 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]
                                         Mutually exclusive with --overview-src
  --min-size <MIN-SIZE>                  Maximum width or height of the smallest overview level.
  --co, --creation-option <KEY>=<VALUE>  Overview creation option [may be repeated]
Advanced Options:
  --oo, --open-option <KEY>=<VALUE>      Open options [may be repeated]

توضیحات (DESCRIPTION)

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

از GDAL 3.12 به بعد، gdal raster overview add می‌تواند به عنوان مرحله‌ای از یک خط لوله (pipeline) به کار رود. در این حالت، نماهای کلی مجازی در خروجی این مرحله تولید می‌شوند و در صورت نوشتن یک فایل GeoTIFF با گزینه ساخت COPY_SRC_OVERVIEWS یا هنگام نوشتن در یک فایل COG (مخفف Cloud Optimized GeoTIFF)، قابلیت تحقق در مرحله پایانی نوشتن را دارند.

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

--co <NAME>=<VALUE>

افزوده‌شده در نسخه 3.12.

گزینه‌های ساخت نمای کلی. می‌تواند تکرار شود.

بسیاری از فرمت‌ها یک یا چند گزینه اختیاری برای ساخت دارند که می‌توان از آن‌ها برای کنترل جزئیات نماهای کلی ایجادشده استفاده کرد. گزینه‌های دردسترس را می‌توان با بررسی OverviewCreationOptionList بازگردانده‌شده توسط gdal --format <FORMAT-NAME> به دست آورد.

بیشتر فرمت‌ها از نماهای کلی خارجی در یک فایل GeoTIFF به‌صورت فایل همراه (sidecar) با پسوند .ovr پشتیبانی می‌کنند. می‌توانید به overview creation options for GeoTIFF مراجعه کنید.

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

--external: ایجاد نماهای کلی خارجی .ovr به عنوان فایل‌های GeoTIFF. هنگام اجرا به عنوان مرحله‌ای از خط لوله در دسترس نیست.

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

اگر از پیش نماهای کلی وجود داشته باشند، در صورت مشخص نشدن سطوح صریح، سطوح متناظر برای تازه‌سازی آن‌ها استفاده خواهند شد.
در غیر این صورت، ضریب‌های توان دوی مناسب برای نمای کلی انتخاب خواهند شد تا زمانی که کوچک‌ترین نمای کلی کوچک‌تر از مقدار سوییچ --min-size شود.

غیرقابل استفاده هم‌زمان با --overview-src

--min-size <val>: حداکثر عرض یا ارتفاع کوچک‌ترین سطح نمای کلی. تنها در صورتی در نظر گرفته می‌شود که سطوح صریح مشخص نشده باشند. مقدار پیش‌فرض ۲۵۶ است.

--overview-src <INPUT>

افزوده‌شده در نسخه 3.12.

افزودن مجموعه‌داده‌های رَستری ورودی مشخص‌شده به عنوان نماهای کلی مجموعه‌داده هدف. نماهای کلی مبدأ می‌توانند از هر فرمت پشتیبانی‌شده در GDAL باشند، به شرطی که تعداد باندها و وسعت مکانی یکسانی با مجموعه‌داده هدف داشته باشند.

این حالت در حال حاضر تنها زمانی پیاده‌سازی شده است که مجموعه‌داده هدف در فرمت GeoTIFF باشد یا هنگام استفاده از --external.

غیرقابل استفاده هم‌زمان با --levels

-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 مقداری را انتخاب می‌کند که بیشترین تکرار را در میان همه نقاط نمونه‌برداری‌شده دارد.

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

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

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

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

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

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

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

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

مثال‌ها (EXAMPLES)

مثال ۱: ساخت نماهای کلی، جاسازی‌شده در فایل TIFF ارائه‌شده، با محاسبه خودکار سطوح

gdal raster overview add -r average abc.tif

مثال ۲: ساخت نماهای کلی، جاسازی‌شده در فایل TIFF ارائه‌شده

gdal raster overview add -r average --levels=2,4,8,16 abc.tif

مثال ۳: ساخت یک فایل نمای کلی فشرده‌شده GeoTIFF خارجی از فایل ERDAS .IMG

gdal raster overview add --external --levels=2,4,8,16 --co COMPRESS=YES erdas.img

مثال ۴: ساخت یک فایل نمای کلی خارجی GeoTIFF فشرده‌شده با JPEG از یک مجموعه‌داده ۳-بانده RGB

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

gdal raster overview add --co OVERVIEW=JPEG --co PHOTOMETRIC=YCBCR \
                         --co INTERLEAVE=PIXEL rgb_dataset.ext 2 4 8 16

مثال ۵: ساخت نماهای کلی برای یک زیرمجموعه‌داده مشخص

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

gdal raster overview add GPKG:file.gpkg:layer

مثال ۶: افزودن ۳ مجموعه‌داده موجود در مقیاس‌های 1:25K، 1:50K و 1:100K به عنوان نماهای کلی my.tif

gdal raster overview add --overview-src ovr_25k.tif --overview-src ovr_50k.tif --overview-src ovr_100k.tif --dataset my.tif

مثال ۷: ساخت یک فایل COG با سطوح نمای کلی که توان دو نیستند

gdal pipeline read input.tif ! reproject --output-crs=EPSG:4326 ! add overview --levels 16,64,128 ! write output.tif --format=COG

نویسندگان (AUTHORS)

Even Rouault <even.rouault@spatialys.com>

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

1998-2026