GDAL-VECTOR-CLEAN-COVERAGE(1)        GDAL        GDAL-VECTOR-CLEAN-COVERAGE(1)

نام (NAME)
       gdal-vector-clean-coverage - حذف فاصله‌ها (شکاف‌ها) و هم‌پوشانی‌ها از یک
       مجموعه‌داده چندضلعی

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


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

          Usage: gdal vector clean-coverage [OPTIONS] <INPUT> <OUTPUT>

          تغییر مرزهای چندضلعی‌ها برای یکسان‌سازی لبه‌های مشترک و حذف فاصله‌ها و هم‌پوشانی‌ها

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

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

          گزینه‌ها (Options):
            -l, --layer, --input-layer <INPUT-LAYER>             نام لایه(های) ورودی [تکرارپذیر] [در خطوط لوله در دسترس نیست]
            -f, --of, --format, --output-format <OUTPUT-FORMAT>  قالب خروجی (مجاز بودن "GDALG") [در خطوط لوله در دسترس نیست]
            --co, --creation-option <KEY>=<VALUE>                گزینه ایجاد [تکرارپذیر] [در خطوط لوله در دسترس نیست]
            --lco, --layer-creation-option <KEY>=<VALUE>         گزینه ایجاد لایه [تکرارپذیر] [در خطوط لوله در دسترس نیست]
            --overwrite                                          آیا بازنویسی روی مجموعه‌داده خروجی موجود مجاز است [در خطوط لوله در دسترس نیست]
            --update                                             آیا مجموعه‌داده موجود در حالت به‌روزرسانی باز شود [در خطوط لوله در دسترس نیست]
            --overwrite-layer                                    آیا بازنویسی روی لایه خروجی موجود مجاز است [در خطوط لوله در دسترس نیست]
            --append                                             آیا الحاق به لایه موجود مجاز است [در خطوط لوله در دسترس نیست]
                                                                 ناسازگار با --upsert
            --output-layer <OUTPUT-LAYER>                        نام لایه خروجی [در خطوط لوله در دسترس نیست]
            --skip-errors                                        چشم‌پوشی از خطاها هنگام نوشتن عوارض [در خطوط لوله در دسترس نیست]
            --active-layer <ACTIVE-LAYER>                        تعیین لایه فعال (در صورت عدم تعیین، همه)
            --snapping-distance <SNAPPING-DISTANCE>              میزان رواداری فاصله برای چسباندن (Snap) گره‌ها
            --merge-strategy <MERGE-STRATEGY>                    الگوریتم اختصاص هم‌پوشانی‌ها به چندضلعی‌های همسایه. MERGE-STRATEGY=longest-border|max-area|min-area|min-index
            --maximum-gap-width <MAXIMUM-GAP-WIDTH>              حداکثر پهنای فاصله (شکاف) جهت بسته شدن

          گزینه‌های پیشرفته (Advanced Options):
            --if, --input-format <INPUT-FORMAT>                  قالب‌های ورودی [تکرارپذیر] [در خطوط لوله در دسترس نیست]
            --oo, --open-option <KEY>=<VALUE>                    گزینه‌های باز کردن [تکرارپذیر] [در خطوط لوله در دسترس نیست]
            --output-oo, --output-open-option <KEY>=<VALUE>      گزینه‌های باز کردن خروجی [تکرارپذیر] [در خطوط لوله در دسترس نیست]
            --upsert                                             درج یا به‌روزرسانی (Upsert) عوارض (شامل 'append') [در خطوط لوله در دسترس نیست]
                                                                 ناسازگار با --append

توضیحات (DESCRIPTION)
       دستور gdal vector clean-coverage مرزهای یک مجموعه‌داده چندضلعی را به
       نحوی اصلاح می‌کند که فاصله‌ها و هم‌پوشانی‌های میان عوارض حذف شده و لبه‌های
       مشترک با استفاده از رأس‌های یکسان تعریف شوند. مجموعه‌داده حاصل یک پوشش
       چندضلعی (Polygonal Coverage) را تشکیل می‌دهد که می‌تواند با gdal vector
       simplify-coverage استفاده شود.

       این دستور همچنین می‌تواند به عنوان مرحله‌ای از gdal vector pipeline به
       کار رود، هرچند نیازمند بارگذاری کل مجموعه‌داده در حافظه به صورت یکجا
       است.

       نکته:
          این دستور نیازمند ساخت GDAL به همراه کتابخانه GEOS (نسخه 3.14 یا
          بالاتر) است.

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

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

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

       --input-layer
              نام لایه مورد پردازش را مشخص می‌کند. به‌طور پیش‌فرض، تمام لایه‌ها
              پردازش خواهند شد.

       --maximum-gap-width <MAXIMUM-GAP-WIDTH>
              بزرگ‌ترین مساحتی را که باید به عنوان یک "فاصله/شکاف" در نظر گرفته
              شده و با یک چندضلعی مجاور ادغام شود تعیین می‌کند. فاصله‌ها ادغام
              خواهند شد مگر اینکه دایره‌ای با شعاع بزرگ‌تر از رواداری مشخص‌شده
              بتواند درون آن فاصله محاط شود. حداکثر پهنای پیش‌فرض فاصله صفر
              است، به این معنی که فاصله‌ها بسته نمی‌شوند.
                [تصویر] مجموعه‌داده چندضلعی پیش از پاک‌سازی (چپ)، پس از پاک‌سازی
                با پارامترهای پیش‌فرض (وسط)، و پس از پاک‌سازی با
                --maximum-gap-width 1 (راست).

       --merge-strategy <MERGE-STRATEGY>
              روشی که بر اساس آن هم‌پوشانی‌ها یا شکاف‌ها باید به چندضلعی‌های مجاور
              اضافه شوند. گزینه‌ها شامل موارد زیر است:

              • longest-border (پیش‌فرض): افزودن مساحت‌ها به چندضلعی‌ای که
                طولانی‌ترین مرز مشترک را با آن دارد

              • max-area: افزودن مساحت‌ها به بزرگ‌ترین چندضلعی مجاور

              • min-area: افزودن مساحت‌ها به کوچک‌ترین چندضلعی مجاور

              • min-index: افزودن مساحت‌ها به چندضلعی مجاوری که ابتدا خوانده
                شده است
                [تصویر] مجموعه‌داده چندضلعی پیش از پاک‌سازی (چپ)، پس از پاک‌سازی
                با راهبرد ادغام "longest-border" (وسط) و --merge-strategy
                max-area (راست).

       --output-layer
              نام لایه‌ای را مشخص می‌کند که عوارض در آن نوشته می‌شوند.  به‌طور
              پیش‌فرض، نام‌های لایه‌های خروجی مشابه نام‌های لایه‌های ورودی خواهد
              بود.

       --snapping-distance <SNAPPING-DISTANCE>
              مرحله چسباندن گره‌ها (Node Snapping) را هنگام چسبیدن رأس‌های نزدیک
              به هم کنترل می‌کند.  به‌طور پیش‌فرض، یک فاصله چسباندن خودکار بر
              اساس تحلیل ورودی تعیین می‌شود. برای خاموش کردن هرگونه چسباندن
              گره‌ها، آن را برابر صفر قرار دهید.
                [تصویر] مجموعه‌داده چندضلعی پیش از پاک‌سازی (چپ)، پس از پاک‌سازی
                با فاصله چسباندن پیش‌فرض (وسط)، و فاصله سخت‌گیرانه‌تر
                --snapping-distance 0.2 (راست). به جابجایی رخ‌داده در گوشه بالا
                سمت چپ چندضلعی در سمت راست توجه کنید.

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

       --active-layer <ACTIVE-LAYER>
              تنظیم لایه فعال. در صورت تعیین، تنها لایه‌ای که با نام خود مشخص
              شده است تحت پردازش قرار می‌گیرد. سایر لایه‌ها تغییری نخواهند کرد.
              اگر این گزینه مشخص نشود، تمام لایه‌ها مشمول پردازش خواهند بود.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

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

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


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

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

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


              گونه‌ای از --append که در آن عملیات OGRLayer::UpsertFeature()
              برای درج یا به‌روزرسانی عوارض به‌جای الحاق با
              OGRLayer::CreateFeature() استفاده می‌شود.

              این قابلیت در حال حاضر تنها در چند درایور پیاده‌سازی شده است:
              GPKG -- GeoPackage vector، Elasticsearch: Geographically Encoded
              Objects for Elasticsearch و MongoDBv3 (درایورهایی که upsert را
              پیاده‌سازی کرده‌اند، قابلیت GDAL_DCAP_UPSERT را ارائه می‌دهند).

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

              برای درایور GPKG، در صورتی که یک ستون با قید UNIQUE وجود داشته
              باشد که کلید اصلی عددی صحیح نباشد، امکان انجام upsert برای
              عوارضی که FID آن‌ها تنظیم نشده یا فاقد اهمیت است نیز وجود دارد
              (گزینه --unset-fid در gdal vector edit می‌تواند برای نادیده گرفتن
              FID عارضه منبع استفاده شود).

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

مثال‌ها (EXAMPLES)
   مثال ۱: ایجاد و سپس ساده‌سازی یک پوشش چندضلعی

          $ gdal vector pipeline read ne_10m_admin_0_countries.shp ! \
                                 make-valid ! \
                                 clean-coverage ! \
                                 simplify-coverage --tolerance 1 ! \
                                 write countries.shp

نویسنده (AUTHOR)
       Dan Baston <dbaston@gmail.com>

حق نشر (COPYRIGHT)
       1998-2026

                                August 18, 2026  GDAL-VECTOR-CLEAN-COVERAGE(1)