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

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

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


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

          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>                        گزینه‌های باز کردن [تکرارپذیر] [در خطوط لوله در دسترس نیست]

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

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

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

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

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

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

       --band <BAND>
              شماره باند منبع (شمارش از یک آغاز می‌شود). در صورت عدم تعیین،
              تمامی باندهای ورودی استفاده می‌شوند.

       --kernel
              کرنل کانولوشن جهت اعمال بر پیکسل‌های منبع در همسایگی هر پیکسل.

              • یا نام یک کرنل شناخته‌شده از میان 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 چندین بار مشخص شود، برای هر ترکیب کرنل و باند ورودی
              یک باند خروجی وجود خواهد داشت.

       --method sum|mean|min|max|stddev|median|mode
              تابع مورد نظر جهت اعمال بر پیکسل‌های وزن‌دار منبع در همسایگی
              تعریف‌شده با کرنل.  پیش‌فرض mean است، مگر زمانی که --kernel روی u،
              v، edge1، edge2، یا یک کرنل تعریف‌شده توسط کاربر که مجموع ضرایب
              آن صفر است تنظیم شده باشد، که در این حالت از sum استفاده می‌شود.

              • sum: مجموع مقادیر پیکسل‌های مشارکت‌کننده منبع ضرب در وزن متناظر
                کرنل را محاسبه می‌کند. این معادل با یک کرنل با مجموع نرمال‌نشده
                ضرایب است.

              • mean: میانگین مقادیر پیکسل‌های مشارکت‌کننده منبع ضرب در وزن
                متناظر کرنل را محاسبه می‌کند. این کار اثر نرمال‌سازی ضرایب کرنل
                را به همراه دارد به طوری که مجموع آن‌ها برابر با یک شود.

              • min: کمینه مقدار پیکسل‌های مشارکت‌کننده منبع ضرب در وزن متناظر
                کرنل را محاسبه می‌کند

              • max: بیشینه مقدار پیکسل‌های مشارکت‌کننده منبع ضرب در وزن متناظر
                کرنل را محاسبه می‌کند

              • stddev: انحراف معیار مقادیر پیکسل‌های مشارکت‌کننده منبع ضرب در
                وزن متناظر کرنل را محاسبه می‌کند

              • median: میانه مقادیر پیکسل‌های مشارکت‌کننده منبع ضرب در وزن
                متناظر کرنل را محاسبه می‌کند

              • mode (اکثریت/نما): پرتکرارترین مقدار پیکسل‌های مشارکت‌کننده منبع
                ضرب در وزن متناظر کرنل را محاسبه می‌کند

       --nodata
              تنظیم مقدار NoData برای مجموعه‌داده خروجی. می‌تواند روی none تنظیم
              شود تا مقدار NoData تعریف‌نشده باقی بماند. اگر --nodata مشخص
              نشود، دستور gdal raster neighbors از مقدار NoData اولین
              مجموعه‌داده منبعی که دارای آن باشد استفاده خواهد کرد.

       --size <SIZE>
              اندازه کرنل. یک عدد فرد بین ۳ و ۹۹.

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

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

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

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

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

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

       --co, --creation-option <NAME>=<VALUE>
              بسیاری از قالب‌ها یک یا چند گزینه اختیاری ایجاد دارند که می‌توانند
              برای کنترل ویژگی‌های خاص فایل ایجادشده استفاده شوند. به عنوان
              مثال، درایور GeoTIFF از گزینه‌های ایجاد برای کنترل فشرده‌سازی و
              کاشی‌بندی شدن فایل پشتیبانی می‌کند.

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

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

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

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

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

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

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

       --ot, --datatype, --output-data-type <OUTPUT-DATA-TYPE>
              نوع داده خروجی از میان Byte، Int8، UInt16، Int16، UInt32، Int32،
              UInt64، Int64، CInt16، CInt32، Float32، Float64، CFloat32،
              CFloat64.

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

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

مثال‌ها (EXAMPLES)
   مثال ۱: محاسبه مشتق افقی و عمودی یک رستر تک‌باند

          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

   مثال ۴: محاسبه فیلتر شفاف‌سازی (Sharpen) یک رستر تک‌باند با تعیین دستی ضرایب
       کرنل

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

نویسنده (AUTHOR)
       Even Rouault <even.rouault@spatialys.com>

حق نشر (COPYRIGHT)
       1998-2026

                                August 18, 2026       GDAL-RASTER-NEIGHBORS(1)