GDAL-VECTOR-BUFFER(1)

GDAL

GDAL-VECTOR-BUFFER(1)

نام (NAME)

gdal-vector-buffer - محاسبه حریم در اطراف هندسه‌های یک مجموعه‌داده برداری

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

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

Usage: gdal vector buffer [OPTIONS] <INPUT> <OUTPUT> <DISTANCE>
محاسبه حریم در اطراف هندسه‌های یک مجموعه‌داده برداری.
آرگومان‌های موضعی (Positional arguments):
  -i, --input <INPUT>                                  مجموعه‌داده‌های برداری ورودی [الزامی] [در خطوط لوله در دسترس نیست]
  -o, --output <OUTPUT>                                مجموعه‌داده برداری خروجی [الزامی] [در خطوط لوله در دسترس نیست]
  --distance <DISTANCE>                                فاصله‌ای که هندسه تا آن گسترش می‌یابد. [الزامی]
گزینه‌های عمومی (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>                        تنظیم لایه فعال (در صورت عدم تعیین، همه)
  --active-geometry <ACTIVE-GEOMETRY>                  نام فیلد هندسه برای محدود کردن پردازش به آن (در صورت عدم تعیین، همه)
  --endcap-style <ENDCAP-STYLE>                        سبک سرپوش انتهایی.. ENDCAP-STYLE=round|flat|square (پیش‌فرض: round)
  --join-style <JOIN-STYLE>                            سبک اتصال.. JOIN-STYLE=round|mitre|bevel (پیش‌فرض: round)
  --mitre-limit <MITRE-LIMIT>                          حد نسبت گوشه تیز/فارسی (فقط بر سبک اتصال فارسی تأثیر می‌گذارد). (پیش‌فرض: 5)
  --quadrant-segments <QUADRANT-SEGMENTS>              تعداد پاره‌خط‌های مورداستفاده برای تقریب یک ربع دایره. (پیش‌فرض: 8)
  --side <SIDE>                                        تعیین اینکه آیا حریم محاسبه‌شده یک‌طرفه باشد یا خیر.. SIDE=both|left|right (پیش‌فرض: both)
گزینه‌های پیشرفته (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 buffer یک POLYGON یا MULTIPOLYGON را محاسبه می‌کند که نمایانگر تمام نقاطی است که فاصله آن‌ها از یک هندسه/جغرافیا کمتر یا مساوی یک فاصله مشخص است. یک فاصله منفی به‌جای گسترش هندسه، آن را منقبض و کوچک‌تر می‌کند. یک فاصله منفی ممکن است یک چندضلعی را به‌طور کامل منقبض و محو کند، که در این حالت POLYGON EMPTY بازگردانده می‌شود. برای نقاط و خطوط، فاصله‌های منفی همواره نتایج خالی بازمی‌گردانند.

برای مشاهده تصویرسازی‌های نگاره‌ای بیشتر از اثر پارامترهای مختلف، مستندات PostGIS ST_Buffer را ببینید.

مجموعه‌داده خروجی همواره به عنوان MULTIPOLYGON نوشته می‌شود، حتی زمانی که ورودی فقط شامل هندسه‌های ساده POLYGON باشد. توجه داشته باشید که فاصله‌های حریم منفی نیز ممکن است نتایج MULTIPOLYGON تولید کنند.

استفاده از فاصله حریم 0 گاهی اوقات می‌تواند هندسه‌های نامعتبر را ترمیم کند، اما روش توصیه‌شده استفاده از gdal vector make-valid برای اعتبارسنجی و ترمیم مطمئن هندسه است.

این دستور همچنین می‌تواند به عنوان یک مرحله از gdal vector pipeline به کار رود.

خروجی GDALG (مجموعه‌داده درجا / جریانی) (GDALG OUTPUT (ON-THE-FLY / STREAMED DATASET))

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

نکته:

این دستور نیازمند بیلد GDAL همگردانی‌شده همراه با کتابخانه GEOS است.

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

--distance <DISTANCE>: شعاع حریم (بافر) در اطراف هندسه ورودی. واحد فاصله بر حسب واحدهای زمین‌مرجع لایه مبدا است.

--endcap-style round|flat|square: سبک سرپوش انتهایی حریم تولیدشده را مشخص می‌کند. مقدار پیش‌فرض round (گرد) است.

[تصویر] خطوط دارای حریم با endcap-style=round، endcap-style=flat و endcap-style=square.

--join-style round|mitre|bevel: سبک اتصال را برای گوشه‌های بیرونی (محدب) بین پاره‌خط‌ها تعیین می‌کند. مقدار پیش‌فرض round (گرد) است.

[تصویر] خطوط دارای حریم با join-style=round، join-style=mitre و join-style=bevel.

--input-layer <NAME>: یک یا چند نام لایه را برای خواندن و پردازش مشخص می‌کند. به‌طور پیش‌فرض، تمام لایه‌ها خوانده و پردازش خواهند شد. برای خواندن و نوشتن تمام لایه‌ها اما پردازش تنها یک زیرمجموعه، از --active-layer استفاده کنید.

--mitre-limit <MITRE-LIMIT>: حد نسبت فارسی‌بُر/تیز (mitre ratio) مورداستفاده برای گوشه‌های بسیار تند را تعیین می‌کند. این گزینه تنها زمانی اعمال می‌شود که از join-style=mitre استفاده شود.
مقدار پیش‌فرض 5 است.

[تصویر] خطوطی با حریم distance=2، همراه با mitre-limit=5 در سمت چپ و mitre-limit=1 در سمت راست.

نسبت گوشه فارسی (mitre ratio) نسبت فاصله از گوشه تا انتهای گوشه بیرونی حریم امتدادیافته است. هنگامی که دو پاره‌خط در یک زاویه تند به هم می‌رسند، اتصال فارسی بسیار فراتر از هندسه اصلی امتداد می‌یابد (و در موارد حاد می‌تواند تا بی‌نهایت ادامه یابد). برای جلوگیری از تولید هندسه‌های غیرمنطقی، حد نسبت فارسی امکان کنترل حداکثر طول گوشه اتصال را فراهم می‌کند. گوشه‌هایی با نسبتی که از این حد فراتر رود، به صورت پخ‌خورده (bevel) درمی‌آیند.

--output-layer <NAME>: نام لایه‌ای که خروجی باید در آن نوشته شود. در صورت عدم تعیین، لایه خروجی همان نام لایه ورودی را خواهد داشت.

--quadrant-segments <QUADRANT-SEGMENTS>: تعداد پاره‌خط‌های مورداستفاده برای تقریب زدن یک انحنا در اتصالات گرد را تعیین می‌کند.
این مقدار، حداکثر خطای تقریب نسبت به منحنی حریم واقعی را تعیین می‌کند. مقدار پیش‌فرض 8 خطای حداکثری کمتر از ۲٪ را در فاصله حریم فراهم می‌آورد. برای خطای حداکثری کمتر از ۱٪، از QS = 12 استفاده کنید. برای خطای حداکثری کمتر از ۰.۱٪، از QS = 18 استفاده کنید. خطا همیشه کمتر از فاصله حریم است (به عبارت دیگر، منحنی حریم محاسبه‌شده همیشه در داخل منحنی واقعی قرار می‌گیرد).

[تصویر] نقاط دارای حریم با quadrant-segments=4 و quadrant-segments=20.

--side both|left|right

تعیین می‌کند که حریم محاسبه‌شده یک‌طرفه باشد یا در هر دو طرف (پیش‌فرض).

مقدار left نشان می‌دهد که حریم در سمت چپ خط ایجاد می‌شود، و right نشان می‌دهد که حریم در سمت راست خط ایجاد می‌شود؛ این جهت بر اساس ترتیب رأس‌های خط (یعنی جهتی که خط رسم شده است) تعیین می‌گردد.

ایجاد حریم یک‌طرفه تنها برای هندسه LINESTRING کاربرد دارد و بر هندسه‌های POINT یا POLYGON تأثیری ندارد، و سبک سرپوش انتهایی اجباراً به مربع (square) تبدیل می‌شود.

[تصویر] خطوط دارای حریم با side=both، side=left و side=right.

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

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

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

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

--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، همچنین امکان درج/به‌روزرسانی عوارضی که FID آن‌ها تنظیم نشده یا فاقد اهمیت است (گزینه --unset-fid در gdal vector edit می‌تواند برای نادیده گرفتن FID از عارضه منبع استفاده شود) وجود دارد، مشروط بر اینکه یک ستون یکتا (UNIQUE) که کلید اصلی عدد صحیح نیست وجود داشته باشد.

کد وضعیت خروجی (RETURN STATUS CODE)

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

مثال‌ها (EXAMPLES)

مثال ۱: محاسبه حریم یک کیلومتری در اطراف هندسه‌های ورودی (با فرض اینکه CRS بر حسب متر است)

$ gdal vector buffer --distance=1000 in.gpkg out.gpkg --overwrite

مثال ۲: ایجاد حریم برای یک مجموعه‌داده نقطه‌ای با ۲۰ پاره‌خط در هر ربع دایره (به‌جای ۸ پیش‌فرض) برای تقریب بهتر دایره

$ gdal vector buffer --distance=20 --quadrant-segments=20 points.gpkg point_buffers.gpkg

مثال ۳: ایجاد حریم برای خطوط در سمت چپ با استفاده از سبک‌های اتصال و سرپوش انتهایی

$ gdal vector buffer --distance=10 --endcap-style=flat --side=left --join-style=mitre --mitre-limit=2 lines.gpkg lines-buffer-endcap.gpkg

مثال ۴: برش و ایجاد حریم برای یک مجموعه‌داده خطی فشرده (zip) به عنوان بخشی از یک خط لوله

Bash

gdal vector pipeline \
! read "/vsizip/lines.zip" \
! clip --bbox 647903,6863599,648703,6864399 \
! buffer --distance=5 \
! write line-buffer.gpkg --overwrite

PowerShell

gdal vector pipeline `
! read "/vsizip/lines.zip" `
! clip --bbox 647903,6863599,648703,6864399 `
! buffer --distance=5 `
! write line-buffer.gpkg --overwrite

نویسنده (AUTHOR)

Even Rouault <even.rouault@spatialys.com>

حق نشر (COPYRIGHT)

1998-2026

August 18, 2026