نام (NAME)

gdal-raster-clean-collar - پاک‌سازی حاشیه مجموعه داده رستر و حذف نویز

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

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

Usage: gdal raster clean-collar [OPTIONS] <INPUT> [<OUTPUT>]
Clean the collar of a raster dataset, removing noise.
Positional arguments:
  -i, --input <INPUT>                                  Input raster dataset [required]
  -o, --output <OUTPUT>                                Output raster dataset
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:
  -f, --of, --format, --output-format <OUTPUT-FORMAT>  Output format
  --co, --creation-option <KEY>=<VALUE>                Creation option [may be repeated]
  --overwrite                                          Whether overwriting existing output dataset is allowed
  --update                                             Whether to open existing dataset in update mode
  --color <COLOR>                                      Transparent color(s): tuple of integer (like 'r,g,b'), 'black', 'white' (default: black) [may be repeated]
  --color-threshold <COLOR-THRESHOLD>                  Select how far from specified transparent colors the pixel values are considered transparent. (default: 15)
  --pixel-distance <PIXEL-DISTANCE>                    Number of consecutive transparent pixels that can be encountered before the giving up search inwards. (default: 2)
  --add-alpha                                          Adds an alpha band to the output dataset.
                                                       Mutually exclusive with --add-mask
  --add-mask                                           Adds a mask band to the output dataset.
                                                       Mutually exclusive with --add-alpha
  --algorithm <ALGORITHM>                              Algorithm to apply. ALGORITHM=floodfill|twopasses (default: floodfill)
Advanced Options:
  --oo, --open-option <KEY>=<VALUE>                    Open options [may be repeated]
  --if, --input-format <INPUT-FORMAT>                  Input formats [may be repeated]

توضیحات (DESCRIPTION)

دستور gdal raster clean-collar یک تصویر (۸ بیتی) را پویش کرده و تمام پیکسل‌هایی را که در حاشیه تصویر تقریباً یا دقیقاً سیاه (پیش‌فرض)، سفید یا یک یا چند رنگ سفارشی هستند، به رنگ سیاه یا سفید تنظیم می‌کند. این قابلیت اغلب برای «اصلاح» عکس‌های هوایی فشرده‌شده با اتلاف (lossy) به کار می‌رود تا هنگام موزاییک کردن تصویر، پیکسل‌های رنگی شفاف در نظر گرفته شوند. در صورتی که هیچ‌کدام از باندهای آلفا یا ماسک تعیین نشده باشند، فرمت خروجی حتماً باید از فشرده‌سازی بدون اتلاف (lossless) استفاده کند.

گزینه‌های ویژه برنامه (PROGRAM-SPECIFIC OPTIONS)

--add-alpha: یک باند آلفا به فایل خروجی اضافه می‌کند. باند آلفا در حاشیه تصویر روی 0 و در سایر نقاط روی 255 تنظیم می‌شود. این گزینه با --add-mask مانعة‌الجمع است (نمی‌توانند هم‌زمان استفاده شوند).

--add-mask: یک باند ماسک به فایل خروجی اضافه می‌کند. باند ماسک در حاشیه تصویر روی 0 و در سایر نقاط روی 255 تنظیم می‌شود. این گزینه با --add-alpha مانعة‌الجمع است (نمی‌توانند هم‌زمان استفاده شوند).

--algorithm floodfill|twopasses

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

الگوریتم twopasses از یک گذر بالا به پایین و سپس یک گذر پایین به بالا استفاده می‌کند. ممکن است در نواحی مقعر (concave) بخش‌هایی نادیده گرفته شوند. این الگوریتم تصویر را خط به خط (یک خط پویش در هر زمان) پردازش می‌کند. پویش به سمت «داخل» از هر دو طرف انجام می‌شود و پیکسل‌ها را به سیاه یا سفید تغییر می‌دهد تا زمانی که دست‌کم به تعداد "non_black_pixels" پیکسل پیدا شوند که بیش از "dist" سطح خاکستری با رنگ سیاه، سفید یا رنگ‌های سفارشی فاصله داشته باشند؛ در این نقطه پویش متوقف می‌شود. پیکسل‌های تقریباً سیاه، سفید یا رنگ‌های سفارشی به سیاه یا سفید تبدیل می‌شوند. این الگوریتم همچنین برای شناسایی فرورفتگی‌ها در بالا یا پایین، تصویر را از بالا به پایین و از پایین به بالا پویش می‌کند.

الگوریتم floodfill (پیش‌فرض) از الگوریتم Flood Fill استفاده می‌کند و برای نواحی مقعر نیز کارایی دارد. این روش نیاز به ایجاد یک مجموعه داده موقت دارد و از twopasses کندتر است. هنگامی که مقداری غیر از صفر برای --pixel-distance استفاده شود، الگوریتم twopasses عملاً به‌عنوان مرحله اولیه floodfill اجرا می‌شود.

--color <c1>,<c2>,<c3>...<cn>|black|white: جستجو برای پیکسل‌های نزدیک به رنگ مشخص‌شده. می‌تواند چندین بار تکرار شود. هنگامی که این گزینه تعیین شود، پیکسل‌هایی که به‌عنوان حاشیه در نظر گرفته می‌شوند روی 0 تنظیم می‌گردند، مگر اینکه فقط white مشخص شده باشد که در این صورت روی 255 تنظیم می‌شوند.

--color-threshold <val>: تعیین می‌کند که مقادیر پیکسل‌ها تا چه اندازه می‌توانند از رنگ‌های سیاه، سفید یا رنگ‌های سفارشی فاصله داشته باشند و همچنان نزدیک به آن‌ها در نظر گرفته شوند. مقدار پیش‌فرض 15 است.

--pixel-distance <val>: تعداد پیکسل‌های شفاف متوالی که می‌توان قبل از توقف جستجو به سمت داخل با آن‌ها مواجه شد. به بیان دیگر، حاشیه به اندازه این تعداد پیکسل گسترش خواهد یافت. مقدار پیش‌فرض 2 است.

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

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

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

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

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

-f, --of, --format, --output-format <OUTPUT-FORMAT>: فرمت رستر خروجی مورد استفاده را مشخص می‌کند. مقادیر مجاز را می‌توان با دستور زیر به دست آورد: gdal --formats | grep raster | grep + | sort

--overwrite: به برنامه اجازه بازنویسی روی فایل یا مجموعه داده مقصد موجود را می‌دهد. در غیر این صورت، به‌طور پیش‌فرض، اگر فایل یا مجموعه داده مقصد از قبل وجود داشته باشد، gdal با خطا متوقف می‌شود.

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

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

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

مثال‌ها (EXAMPLES)

مثال ۱: ویرایش درجا یک مجموعه داده با استفاده از رنگ سیاه پیش‌فرض به‌عنوان رنگ حاشیه

$ gdal raster clean-collar --update my.tif

مثال ۲: ایجاد یک مجموعه داده جدید با استفاده از رنگ سیاه یا سفید به‌عنوان رنگ حاشیه، با در نظر گرفتن مقادیر بازه [0,5] به‌عنوان سیاه و مقادیر بازه [250,255] به‌عنوان سفید. این دستور همچنین یک باند آلفا به مجموعه داده خروجی اضافه می‌کند.

$ gdal raster clean-collar --add-alpha --color=black --color=white --color-threshold=5 in.tif out.tif

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

Even Rouault <even.rouault@spatialys.com>

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

1998-2026