GDAL-RASTER-POLYGONIZE(1)            GDAL            GDAL-RASTER-POLYGONIZE(1)

نام (NAME)
       gdal-raster-polygonize - ساخت مجموعه‌داده عارضه چندضلعی از یک باند رستر

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


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

          Usage: gdal raster polygonize [OPTIONS] <INPUT> <OUTPUT>

          ساخت مجموعه‌داده عارضه چندضلعی از یک باند رستر.

          آرگومان‌های مکانی:
            -i, --input <INPUT>                                  مجموعه‌داده‌های رستر ورودی [الزامی] [در خط‌لوله‌ها دردسترس نیست]
            -o, --output <OUTPUT>                                مجموعه‌داده برداری خروجی [الزامی] [در خط‌لوله‌ها دردسترس نیست]

          گزینه‌های عمومی:
            -h, --help                                           نمایش پیام راهنما و خروج
            --json-usage                                         نمایش نحوه استفاده به صورت یک سند JSON و خروج
            --config <KEY>=<VALUE>                               گزینه پیکربندی [تکرارپذیر]
            -q, --quiet                                          حالت بی‌صدا (بدون نوار پیشرفت یا پیام هشدار) [در خط‌لوله‌ها دردسترس نیست]

          گزینه‌ها:
            -f, --of, --format, --output-format <OUTPUT-FORMAT>  قالب خروجی (قالب "GDALG" مجاز است) [در خط‌لوله‌ها دردسترس نیست]
            --co, --creation-option <KEY>=<VALUE>                گزینه ساخت [تکرارپذیر] [در خط‌لوله‌ها دردسترس نیست]
            --lco, --layer-creation-option <KEY>=<VALUE>         گزینه ساخت لایه [تکرارپذیر] [در خط‌لوله‌ها دردسترس نیست]
            --overwrite                                          تعیین مجاز بودن رونویسی مجموعه‌داده خروجی موجود [در خط‌لوله‌ها دردسترس نیست]
            --update                                             تعیین باز کردن مجموعه‌داده موجود در حالت به‌روزرسانی [در خط‌لوله‌ها دردسترس نیست]
            --overwrite-layer                                    تعیین مجاز بودن رونویسی لایه خروجی موجود [در خط‌لوله‌ها دردسترس نیست]
            --append                                             تعیین مجاز بودن الحاق به لایه موجود [در خط‌لوله‌ها دردسترس نیست]
            --output-layer <OUTPUT-LAYER>                        نام لایه خروجی
            -b, --band <BAND>                                    باند ورودی (نمایه با شروع از ۱) (پیش‌فرض: 1)
            --attribute-name <ATTRIBUTE-NAME>                    نام فیلد حاوی مقدار پیکسل (پیش‌فرض: DN)
            -c, --connect-diagonal-pixels                        در نظر گرفتن پیکسل‌های مورب به عنوان متصل

          گزینه‌های پیشرفته:
            --if, --input-format <INPUT-FORMAT>                  قالب‌های ورودی [تکرارپذیر] [در خط‌لوله‌ها دردسترس نیست]
            --oo, --open-option <KEY>=<VALUE>                    گزینه‌های باز کردن [تکرارپذیر] [در خط‌لوله‌ها دردسترس نیست]
            --output-oo, --output-open-option <KEY>=<VALUE>      گزینه‌های باز کردن خروجی [تکرارپذیر] [در خط‌لوله‌ها دردسترس نیست]

توضیحات (DESCRIPTION)
       دستور gdal raster polygonize برای تمام نواحی متصل از پیکسل‌ها در رستر که
       دارای مقدار پیکسل مشترکی هستند، چندضلعی‌های برداری ایجاد می‌کند.  هر
       چندضلعی با یک صفت ایجاد می‌شود که مقدار پیکسل آن چندضلعی را مشخص می‌کند.
       پیکسل‌هایی که روی مقدار NoData تنظیم شده‌اند، یا با یک باند ماسک خارجی
       پوشانده (mask) شده‌اند، در پردازش لحاظ نمی‌شوند.

       این ابزار می‌تواند مجموعه‌داده برداری خروجی را در صورت عدم وجود ایجاد
       کند، در غیر این صورت می‌تواند به مجموعه‌داده موجود الحاق نماید.

       این ابزار بر پایه تابع :GDALPolygonize() توسعه یافته است که حاوی جزئیات
       بیشتری درباره این الگوریتم می‌باشد.

       از GDAL 3.12 به بعد، این الگوریتم می‌تواند بخشی از یک gdal pipeline
       باشد.
         [تصویر] چندضلعی‌سازی یک ورودی رستر ۳×۳. شکل میانی رفتار پیش‌فرض را نشان
         می‌دهد که در آن، برای نواحی پیکسلی که فقط به یک همسایه مورب متصل
         هستند، چندضلعی‌های جداگانه ایجاد می‌شود.  در شکل سمت راست،
         --connect-diagonal-pixels مشخص شده است و برای پیکسل‌های با مقدار ۴ یک
         چندضلعی واحد ایجاد شده است.

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


خروجی GDALG (مجموعه‌داده در لحظه / جریانی) (GDALG OUTPUT (ON-THE-FLY / STREAMED
       DATASET))
       این برنامه از سریال‌سازی خط فرمان به عنوان یک فایل JSON با استفاده از
       قالب خروجی GDALG پشتیبانی می‌کند.  فایل حاصل را می‌توان سپس به عنوان یک
       مجموعه‌داده برداری با استفاده از درایور GDALG: GDAL Streamed Algorithm
       باز کرد، و خط‌لوله مشخص شده را به صورت در لحظه (on-the-fly) یا جریانی
       (streamed) اعمال نمود.

       نکته:
          با این حال، این الگوریتم ذاتاً با حالت جریانی سازگار نیست. در نتیجه،
          یک مجموعه‌داده موقت در حافظه ایجاد خواهد شد که ممکن است زمان پردازش
          قابل‌توجهی را هنگام باز کردن به همراه داشته باشد.

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

       --attribute-name <ELEVATION-NAME>
              نام فیلدی که باید ایجاد شود (پیش‌فرض: "DN").

       -b, --band <BAND>
              یک باند خاص را برای چندضلعی‌سازی انتخاب می‌کند. پیش‌فرض باند 1 است.

       -c, --connect-diagonal-pixels
              پیکسل‌های مورب (پیکسل‌های گوشه‌ها) را متصل به هم در نظر می‌گیرد.
              رفتار پیش‌فرض تنها متصل در نظر گرفتن پیکسل‌هایی است که با لبه‌ها در
              تماس هستند، که معادل اتصال ۴گانه (4-connectivity) است. هنگامی که
              این گزینه انتخاب شود، الگوریتم پیکسل‌های گوشه را نیز متصل در نظر
              می‌گیرد، که معادل اتصال ۸گانه (8-connectivity) است.

       --nln, --output-layer <OUTPUT-LAYER>
              نامی برای لایه برداری خروجی مشخص می‌کند. پیش‌فرض "polygonize" است.

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

       --append
              تعیین مجاز بودن الحاق عارضه‌ها به لایه(های) موجود.  این گزینه
              همچنین در صورت عدم وجود مجموعه‌داده خروجی، آن را ایجاد می‌کند.

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

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

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

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

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

       --lco, --layer-creation-option <NAME>=<VALUE>
              بسیاری از قالب‌ها یک یا چند گزینه اختیاری ساخت لایه دارند که
              می‌توانند برای کنترل جزئیات لایه ایجادشده به کار روند. برای مثال،
              درایور GeoPackage از گزینه‌های ساخت لایه برای کنترل شناسه عارضه
              یا نام ستون هندسه (geometry)، تنظیم شناسه یا توضیحات و غیره
              پشتیبانی می‌کند.

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

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

              توجه داشته باشید که گزینه‌های ساخت لایه با گزینه‌های ساخت
              مجموعه‌داده متفاوت هستند.

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

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

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

       --output-open-option, --output-oo <NAME>=<VALUE>
              افزوده شده در نسخه 3.12.


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

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

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

       --overwrite-layer
              تعیین مجاز بودن رونویسی لایه برداری خروجی موجود.

       --update
              تعیین باز کردن مجموعه‌داده خروجی موجود در حالت به‌روزرسانی.

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

مثال‌ها (EXAMPLES)
   مثال ۱: ساخت یک shapefile با چندضلعی‌ها برای نواحی متصل باند ۱ از GeoTIFF
       ورودی.

             gdal raster polygonize input.tif polygonize.shp

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

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

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