GDAL-VECTOR-CHECK-GEOMETRY(1) GDAL GDAL-VECTOR-CHECK-GEOMETRY(1)

gdal-vector-check-geometry - بررسی یک مجموعه‌داده از نظر هندسه‌های نامعتبر یا غیرساده

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

Usage: gdal vector check-geometry [OPTIONS] <INPUT> <OUTPUT>
Check a dataset for invalid geometries
Positional arguments:
  -i, --input <INPUT>                                  Input vector datasets [required] [not available in pipelines]
  -o, --output <OUTPUT>                                Output vector dataset [required] [not available in pipelines]
Common Options:
  -h, --help                                           Display help message and exit
  --json-usage                                         Display usage as JSON document and exit
  --config <KEY>=<VALUE>                               Configuration option [may be repeated]
  -q, --quiet                                          Quiet mode (no progress bar or warning message) [not available in pipelines]
Options:
  -l, --layer, --input-layer <INPUT-LAYER>             Input layer name(s) [may be repeated] [not available in pipelines]
  -f, --of, --format, --output-format <OUTPUT-FORMAT>  Output format ("GDALG" allowed) [not available in pipelines]
  --co, --creation-option <KEY>=<VALUE>                Creation option [may be repeated] [not available in pipelines]
  --lco, --layer-creation-option <KEY>=<VALUE>         Layer creation option [may be repeated] [not available in pipelines]
  --overwrite                                          Whether overwriting existing output dataset is allowed [not available in pipelines]
  --update                                             Whether to open existing dataset in update mode [not available in pipelines]
  --overwrite-layer                                    Whether overwriting existing output layer is allowed [not available in pipelines]
  --append                                             Whether appending to existing layer is allowed [not available in pipelines]
                                                       Mutually exclusive with --upsert
  --output-layer <OUTPUT-LAYER>                        Output layer name [not available in pipelines]
  --skip-errors                                        Skip errors when writing features [not available in pipelines]
  --no-create-empty-layers                             Avoid creating layers to which no features will be written [not available in pipelines]
  --include-field <INCLUDE-FIELD>                      Fields from input layer to include in output (special values: ALL and NONE) (default: NONE) [may be repeated]
  --include-valid                                      Include valid inputs in output, with empty geometry
  --geometry-field <GEOMETRY-FIELD>                    Name of geometry field to check
Advanced Options:
  --if, --input-format <INPUT-FORMAT>                  Input formats [may be repeated] [not available in pipelines]
  --oo, --open-option <KEY>=<VALUE>                    Open options [may be repeated] [not available in pipelines]
  --output-oo, --output-open-option <KEY>=<VALUE>      Output open options [may be repeated] [not available in pipelines]
  --upsert                                             Upsert features (implies 'append') [not available in pipelines]
                                                       Mutually exclusive with --append

دستور gdal vector check-geometry بررسی می‌کند که آیا عناصر مجزای یک مجموعه‌داده طبق استاندارد عوارض ساده OGC معتبر و ساده هستند یا خیر. برای هر عارضه نامعتبر یا غیرساده، شرحی از خطا و در بیشتر موارد، موقعیت نقطه‌ای خطا را در خروجی ارائه می‌دهد.

بسته به نوع هندسه ورودی، بررسی‌های زیر انجام می‌شود:

  • چندضلعی‌ها (Polygon) و چندچندضلعی‌ها (MultiPolygon) از نظر معتبر بودن بررسی می‌شوند. حتی اگر چندین علت برای نامعتبر بودن وجود داشته باشد، یک نقطه خطای تکی گزارش خواهد شد.
  • رشته‌خط‌ها (LineString) و چندرشته‌خط‌ها (MultiLineString) از نظر ساده بودن بررسی می‌شوند. اگر GDAL با نسخه 3.14 یا بالاتر کتابخانه GEOS ساخته شده باشد، تمام نقاط خودهم‌پوشانی (self-intersection) گزارش می‌شوند. در نسخه‌های قدیمی‌تر، مکان‌های خودهم‌پوشانی گزارش نمی‌شوند.
  • مجموعه‌های هندسی (GeometryCollection) بررسی می‌شوند تا عناصر مجزای آن‌ها معتبر / ساده باشند. حتی اگر چندین علت برای نامعتبر بودن وجود داشته باشد، یک نقطه خطای تکی گزارش خواهد شد.
  • سایر انواع هندسه بررسی نمی‌شوند.

بررسی اعتبار/سادگی توسط کتابخانه GEOS انجام می‌شود و باید با نتایج نرم‌افزارهایی چون PostGIS، QGIS و shapely که از این کتابخانه استفاده می‌کنند سازگار باشد. GEOS نقاط تکراری را علتی برای نامعتبر بودن یا غیرساده بودن در نظر نمی‌گیرد. برای اطلاعات بیشتر درباره آزمون اعتبار انجام‌شده توسط gdal vector check-geometry و نمونه‌هایی از خطاهای گزارش‌شده، Geometry Validity را ببینید.

[تصویر] مکان‌های خطای گزارش‌شده توسط gdal vector check-geometry برای ورودی‌های Polygon، MultiPolygon و LineString.

هشدار:

هندسه‌های منحنی پیش از تبدیل به GEOS خطی‌سازی (linearize) می‌شوند. هندسه‌های خطی‌شده ممکن است در جایی که هندسه‌های اصلی نامعتبر هستند، معتبر/ساده باشند و برعکس.

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

نکته:

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

برای لایه‌هایی که چندین فیلد هندسه دارند، نام فیلد هندسه مورد نظر برای آزمون را مشخص می‌کند. به‌طور پیش‌فرض از نخستین فیلد هندسه استفاده خواهد شد.
افزوده شده در نسخه 3.12.1.

فیلد(های) اختیاری برای کپی شدن از عوارض ورودی به خروجی. از نسخه GDAL 3.13 به بعد، مقدار ALL می‌تواند برای گنجاندن تمام فیلدها از لایه مبدا استفاده شود.

گنجاندن عوارض مربوط به هندسه‌های معتبر/ساده در خروجی، با حفظ تناظر یک‌به‌یک (1:1) بین عوارض ورودی و خروجی.
نام یک یا چند لایه را برای پردازش مشخص می‌کند. به‌طور پیش‌فرض، تمام لایه‌ها پردازش خواهند شد.
نام لایه‌ای را که عوارض در آن نوشته خواهند شد مشخص می‌کند. اگر مشخص نشود و تنها یک لایه ورودی وجود داشته باشد، از نام "error_location" استفاده خواهد شد. اگر مشخص نشود و چندین لایه ورودی وجود داشته باشد، عوارض مربوط به هر لایه ورودی در یک لایه خروجی جداگانه با قالب "error_location_{INPUT_LAYER}" نوشته خواهند شد.

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

می‌تواند تکرار شود.

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

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

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

می‌تواند تکرار شود.

بسیاری از قالب‌ها یک یا چند گزینه اختیاری ساخت لایه دارند که می‌توانند برای کنترل جزئیات لایه ایجادشده استفاده شوند. برای نمونه، درایور GeoPackage از گزینه‌های ساخت لایه برای کنترل شناسه عارضه یا نام ستون هندسه، تنظیم شناسه یا توضیحات و غیره پشتیبانی می‌کند.

می‌تواند تکرار شود.

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

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

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

جلوگیری از ساخت لایه‌هایی که هیچ عارضه‌ای در آن‌ها نوشته نخواهد شد.

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

می‌تواند تکرار شود.

کدام قالب برداری خروجی استفاده شود. مقادیر مجاز را می‌توان با دستور زیر به دست آورد: gdal --formats | grep vector | grep rw | sort
افزوده شده در نسخه 3.12.

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

می‌تواند تکرار شود.

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

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

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

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

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

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

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

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

$ gdal vector check-geometry ne_10m_admin_0_countries.shp \
         --quiet \
         -f CSV \
         --lco GEOMETRY=AS_XY \
         --lco SEPARATOR=TAB \
         /vsistdout/
# X      Y       error
# 35.6210871060001       23.1392929140001        Ring Self-intersection

Dan Baston <dbaston@gmail.com>

1998-2026

August 18, 2026