GDAL-RASTER-NEIGHBORS(1) GDAL GDAL-RASTER-NEIGHBORS(1)

gdal-raster-neighbors - محاسبه مقدار هر پیکسل بر اساس همسایگان آن (آمار کانونی)

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

Usage: gdal raster neighbors [OPTIONS] <INPUT> <OUTPUT>
محاسبه مقدار هر پیکسل از همسایگان آن (آمار کانونی)
آرگومان‌های موضعی (Positional arguments):
  -i, --input <INPUT>                                      مجموعه‌داده‌های رستری ورودی [الزامی] [در خطوط لوله در دسترس نیست]
  -o, --output <OUTPUT>                                    مجموعه‌داده رستری خروجی [الزامی] [در خطوط لوله در دسترس نیست]
گزینه‌های عمومی (Common Options):
  -h, --help                                               نمایش پیام راهنما و خروج
  --json-usage                                             نمایش نحوه استفاده به صورت سند JSON و خروج
  --config <KEY>=<VALUE>                                   گزینه پیکربندی [تکرارپذیر]
  -q, --quiet                                              حالت بی‌صدا (بدون نوار پیشرفت یا پیام هشدار) [در خطوط لوله در دسترس نیست]
گزینه‌ها (Options):
  -f, --of, --format, --output-format <OUTPUT-FORMAT>      قالب خروجی (مجاز بودن "GDALG") [در خطوط لوله در دسترس نیست]
  --co, --creation-option <KEY>=<VALUE>                    گزینه ایجاد [تکرارپذیر] [در خطوط لوله در دسترس نیست]
  --overwrite                                              آیا بازنویسی روی مجموعه‌داده خروجی موجود مجاز است [در خطوط لوله در دسترس نیست]
                                                           ناسازگار با --append
  --append                                                 الحاق به عنوان یک زیرمجموعه‌داده به خروجی موجود [در خطوط لوله در دسترس نیست]
                                                           ناسازگار با --overwrite
  -b, --band <BAND>                                        باند ورودی (شاخص با شروع از ۱)
  --method <METHOD>                                        روش ترکیب پیکسل‌های وزن‌دار منبع. METHOD=mean|sum|min|max|stddev|median|mode [تکرارپذیر]
  --size <SIZE>                                            اندازه همسایگی
  --kernel <KERNEL>                                        کرنل(های) کانولوشن جهت اعمال [۱.. مقادیر] [الزامی]
  --ot, --datatype, --output-data-type <OUTPUT-DATA-TYPE>  نوع داده خروجی. OUTPUT-DATA-TYPE=UInt8|Int8|UInt16|Int16|UInt32|Int32|UInt64|Int64|CInt16|CInt32|Float16|Float32|Float64|CFloat32|CFloat64 (پیش‌فرض: Float64)
  --nodata <NODATA>                                        اختصاص مقدار بی‌داده (nodata) مشخص به باندهای خروجی ('none'، مقدار عددی، 'nan'، 'inf'، '-inf')
گزینه‌های پیشرفته (Advanced Options):
  --if, --input-format <INPUT-FORMAT>                      قالب‌های ورودی [تکرارپذیر] [در خطوط لوله در دسترس نیست]
  --oo, --open-option <KEY>=<VALUE>                        گزینه‌های باز کردن [تکرارپذیر] [در خطوط لوله در دسترس نیست]

دستور gdal raster neighbors یک کرنل (ماتریس کانولوشن) و یک روش را برای محاسبه مقدار پیکسل هدف از روی همسایگی مقدار پیکسل منبع اعمال می‌کند.

در لبه بالایی، مقادیر ردیف اول تکرار می‌شوند تا پنجره منبع را به صورت مجازی به تعداد ردیف‌هایی برابر با شعاع کرنل گسترش دهند؛ و به همین ترتیب برای لبه‌های پایین، چپ و راست نیز عمل می‌شود. این راهبرد ممکن است بسته به کرنل اعمال‌شده به طور بالقوه منجر به نتایج غیرمنتظره شود.

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

این الگوریتم می‌تواند بخشی از یک gdal pipeline یا gdal raster pipeline باشد.

[تصویر] مجموعه‌داده رستری پیش از جمع (چپ) و پس از جمع (راست) با یک کرنل ۳×۳ هم‌وزن. مقادیر NoData برای اهداف جمع صفر در نظر گرفته می‌شوند. در جایی که پنجره کرنل فراتر از لبه مجموعه‌داده امتداد می‌یابد، سلول‌های لبه تکرار می‌شوند.

این برنامه از سریالی‌سازی خط فرمان به عنوان یک فایل JSON با استفاده از قالب خروجی GDALG پشتیبانی می‌کند. سپس فایل حاصل می‌تواند به عنوان یک مجموعه‌داده رستری با استفاده از درایور GDALG: GDAL Streamed Algorithm باز شود و خط لوله تعیین‌شده را به صورت در لحظه / جریانی اعمال کند.

شماره باند منبع (شمارش از یک آغاز می‌شود). در صورت عدم تعیین، تمامی باندهای ورودی استفاده می‌شوند.
کرنل کانولوشن جهت اعمال بر پیکسل‌های منبع در همسایگی هر پیکسل.
•
یا نام یک کرنل شناخته‌شده از میان edge1، edge2، sharpen، gaussian، یا unsharp-masking، متناظر با این کرنل‌ها (ماتریس‌های کانولوشن)، به همراه موارد افزوده زیر:
  • equal متناظر با یک کرنل با تمام ضرایب برابر با یک (اندازه کرنل می‌تواند هر عدد فردی بین ۳ تا ۹۹ باشد):


    \begin{align}

    \begin{bmatrix} 1 & 1 & 1\\ 1 & 1 & 1 \\ 1 & 1 & 1 \end{bmatrix} \end{align}


    برای روش mean، این معادل فیلتر مات‌کننده جعبه‌ای (Box Blur) است.

  • u متناظر با یک مشتق افقی با ضرایب زیر:


    \begin{align}

    \begin{bmatrix} 0 & 0 & 0\\ -0.5 & 0 & 0.5 \\ 0 & 0 & 0 \end{bmatrix} \end{align}


  • v متناظر با یک مشتق عمودی با ضرایب زیر:


    \begin{align}

    \begin{bmatrix} 0 & -0.5 & 0\\ 0 & 0 & 0 \\ 0 & 0.5 & 0 \end{bmatrix} \end{align}


کرنل‌های edge1، edge2، sharpen، u و v فقط برای اندازه کرنل برابر با ۳ پشتیبانی می‌شوند.

کرنل gaussian برای اندازه کرنل برابر با ۳ یا ۵ پشتیبانی می‌شود.

کرنل unsharp-masking برای اندازه کرنل برابر با ۵ پشتیبانی می‌شود.

•
یا مقادیر ضرایب کرنل به عنوان یک ماتریس مربعی با پهنا و ارتفاع N، که در آن N یک عدد فرد است، به صورت [[val00, val01, ..., val0N],[val10, val11, ..., val1N],...,[valN0, valN1, ..., valNN]].

اگر --method روی mean تنظیم شود، این کار اثر محاسبه مجموع پیکسل‌های وزن‌دار منبع (مشارکت‌کننده، یعنی غیر nodata) و تقسیم آن بر مجموع ضرایب موجود در کرنل را خواهد داشت.

اگر --kernel چندین بار مشخص شود، برای هر ترکیب کرنل و باند ورودی یک باند خروجی وجود خواهد داشت.

تابع مورد نظر جهت اعمال بر پیکسل‌های وزن‌دار منبع در همسایگی تعریف‌شده با کرنل. پیش‌فرض mean است، مگر زمانی که --kernel روی u، v، edge1، edge2، یا یک کرنل تعریف‌شده توسط کاربر که مجموع ضرایب آن صفر است تنظیم شده باشد، که در این حالت از sum استفاده می‌شود.
  • sum: مجموع مقادیر پیکسل‌های مشارکت‌کننده منبع ضرب در وزن متناظر کرنل را محاسبه می‌کند. این معادل با یک کرنل با مجموع نرمال‌نشده ضرایب است.
  • mean: میانگین مقادیر پیکسل‌های مشارکت‌کننده منبع ضرب در وزن متناظر کرنل را محاسبه می‌کند. این کار اثر نرمال‌سازی ضرایب کرنل را به همراه دارد به طوری که مجموع آن‌ها برابر با یک شود.
  • min: کمینه مقدار پیکسل‌های مشارکت‌کننده منبع ضرب در وزن متناظر کرنل را محاسبه می‌کند
  • max: بیشینه مقدار پیکسل‌های مشارکت‌کننده منبع ضرب در وزن متناظر کرنل را محاسبه می‌کند
  • stddev: انحراف معیار مقادیر پیکسل‌های مشارکت‌کننده منبع ضرب در وزن متناظر کرنل را محاسبه می‌کند
  • median: میانه مقادیر پیکسل‌های مشارکت‌کننده منبع ضرب در وزن متناظر کرنل را محاسبه می‌کند
  • mode (اکثریت/نما): پرتکرارترین مقدار پیکسل‌های مشارکت‌کننده منبع ضرب در وزن متناظر کرنل را محاسبه می‌کند
تنظیم مقدار NoData برای مجموعه‌داده خروجی. می‌تواند روی none تنظیم شود تا مقدار NoData تعریف‌نشده باقی بماند. اگر --nodata مشخص نشود، دستور gdal raster neighbors از مقدار NoData اولین مجموعه‌داده منبعی که دارای آن باشد استفاده خواهد کرد.
اندازه کرنل. یک عدد فرد بین ۳ و ۹۹.

نکته:

زمان محاسبات متناسب با مجذور اندازه کرنل است.

برای کرنل‌های edge1، edge2، sharpen، u، v، gaussian، equal، مقدار پیش‌فرض ۳ است.

برای کرنل unsharp-masking، مقدار پیش‌فرض ۵ است.

برای کرنل‌هایی که با مقادیر ضرایب خود تعیین می‌شوند، این مقدار از شکل ماتریس استنباط می‌شود.

الحاق رستر ورودی به عنوان یک زیرمجموعه‌داده جدید به فایل خروجی موجود. تنها با درایورهایی کار می‌کند که از افزودن زیرمجموعه‌داده‌ها پشتیبانی می‌کنند مانند GTiff -- GeoTIFF File Format و GPKG -- GeoPackage raster. این گزینه همچنین در صورت عدم وجود مجموعه‌داده خروجی، آن را ایجاد می‌کند.
بسیاری از قالب‌ها یک یا چند گزینه اختیاری ایجاد دارند که می‌توانند برای کنترل ویژگی‌های خاص فایل ایجادشده استفاده شوند. به عنوان مثال، درایور GeoTIFF از گزینه‌های ایجاد برای کنترل فشرده‌سازی و کاشی‌بندی شدن فایل پشتیبانی می‌کند.

تکرارپذیر است.

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

نام قالب/درایوری که برای باز کردن فایل(های) ورودی تلاش می‌شود. معمولاً نیازی به تعیین آن نیست، اما می‌توان از آن برای چشم‌پوشی از تشخیص خودکار درایور، هنگامی که در انتخاب درایور مناسب ناموفق است، استفاده کرد. این گزینه می‌تواند چندین بار برای تعیین چندین درایور کاندید تکرار شود. توجه داشته باشید که این گزینه آن درایورها را مجبور به باز کردن مجموعه‌داده نمی‌کند. به ویژه، برخی از درایورها نیازمندی‌هایی برای پسوند فایل دارند.

تکرارپذیر است.

گزینه باز کردن مجموعه‌داده (مختص قالب).

تکرارپذیر است.

تعیین اینکه از کدام قالب رستری خروجی استفاده شود. مقادیر مجاز را می‌توان با دستور زیر به دست آورد: gdal --formats | grep raster | grep rw | sort
نوع داده خروجی از میان Byte، Int8، UInt16، Int16، UInt32، Int32، UInt64، Int64، CInt16، CInt32، Float32، Float64، CFloat32، CFloat64.
اجازه دادن به برنامه برای بازنویسی روی فایل یا مجموعه‌داده هدف موجود. در غیر این صورت، به‌طور پیش‌فرض، اگر فایل یا مجموعه‌داده هدف از قبل وجود داشته باشد، gdal با خطا متوقف می‌شود.

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

gdal raster neighbors --kernel u --kernel v in.tif uv.tif

gdal raster neighbors --kernel equal --method mean in.tif mean.tif

gdal raster neighbors --kernel equal --size 5 --method max in.tif max.tif

gdal raster neighbors "--kernel=[[0,-1,0],[-1,5,-1],[0,-1,0]]" in.tif sharpen.tif

Even Rouault <even.rouault@spatialys.com>

1998-2026

August 18, 2026