GDAL-VECTOR-CLIP(1)

GDAL

GDAL-VECTOR-CLIP(1)

نام (NAME)

gdal-vector-clip - برش مجموعه‌داده برداری

در نگارش 3.11 اضافه شد.

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

کاربرد: gdal vector clip [OPTIONS] <INPUT> <OUTPUT>
برش یک مجموعه‌داده برداری.
آرگومان‌های موقعیتی:
  -i, --input <INPUT>                                  مجموعه‌داده‌های برداری ورودی [الزامی] [در خط‌لوله‌ها در دسترس نیست]
  -o, --output <OUTPUT>                                مجموعه‌داده برداری خروجی [الزامی] [در خط‌لوله‌ها در دسترس نیست]
گزینه‌های عمومی:
  -h, --help                                           نمایش پیام راهنما و خروج
  --json-usage                                         نمایش نحوه استفاده در قالب سند JSON و خروج
  --config <KEY>=<VALUE>                               گزینه پیکربندی [می‌تواند تکرار شود]
  -q, --quiet                                          حالت بی‌صدا (بدون نوار پیشرفت یا پیام هشدار) [در خط‌لوله‌ها در دسترس نیست]
گزینه‌ها:
  -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>                        تنظیم لایه فعال (اگر مشخص نشود، همه)
  --bbox <BBOX>                                        جعبه محصورکننده برش به صورت xmin,ymin,xmax,ymax
                                                       مانعة‌الجمع با --geometry و --like
  --bbox-crs <BBOX-CRS>                                سامانه مرجع مختصات (CRS) جعبه محصورکننده برش
  --geometry <GEOMETRY>                                هندسه برش (WKT یا GeoJSON)
                                                       مانعة‌الجمع با --bbox و --like
  --geometry-crs <GEOMETRY-CRS>                        سامانه مرجع مختصات (CRS) هندسه برش
  --like <DATASET>                                     مجموعه‌داده برای استفاده به عنوان الگو جهت محدوده‌ها
                                                       مانعة‌الجمع با --bbox و --geometry
  --like-sql <SELECT-STATEMENT>                        دستور SELECT برای اجرا روی مجموعه‌داده 'like'
                                                       مانعة‌الجمع با --like-where
  --like-layer <LAYER-NAME>                            نام لایه در مجموعه‌داده 'like'
  --like-where <WHERE-EXPRESSION>                      بند WHERE در SQL برای اجرا روی مجموعه‌داده 'like'
                                                       مانعة‌الجمع با --like-sql
گزینه‌های پیشرفته:
  --if, --input-format <INPUT-FORMAT>                  قالب‌های ورودی [می‌تواند تکرار شود] [در خط‌لوله‌ها در دسترس نیست]
  --oo, --open-option <KEY>=<VALUE>                    گزینه‌های باز کردن [می‌تواند تکرار شود] [در خط‌لوله‌ها در دسترس نیست]
  --output-oo, --output-open-option <KEY>=<VALUE>      گزینه‌های باز کردن خروجی [می‌تواند تکرار شود] [در خط‌لوله‌ها در دسترس نیست]
  --upsert                                             درج یا به‌روزرسانی (Upsert) عوارض (مستلزم 'append') [در خط‌لوله‌ها در دسترس نیست]
                                                       مانعة‌الجمع با --append

می‌توان از gdal vector clip برای برش دادن یک مجموعه داده برداری با استفاده از مختصات زمین‌مرجع استفاده کرد.

باید حتماً یکی از گزینه‌های --bbox، --geometry یا --like مشخص شود.

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

عملیات برش گاهی منجر به تولید هندسه‌هایی می‌شود که با نوع هندسه لایه سازگار نیستند. این برنامه برای لایه‌هایی که از یک نوع هندسی تکی هستند (مانند point،‏ linestring یا polygon)، چند‌هندسه‌ها (multi-geometries) یا مجموعه‌های هندسی را به بخش‌های تشکیل‌دهنده‌شان تفکیک کرده و تنها بخش‌هایی را که از همان نوع هستند نگه می‌دارد. همچنین انواع هندسی تکی (مانند polygons) را به انواع چند‌هندسی (مانند multi-polygons) ارتقا می‌دهد. اگر کاربر نیاز به حفظ هر نوع اشتراکی داشته باشد، لایه باید از نوع wkbUnknown (هر نوع هندسه) استفاده کند.

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

--bbox <xmin>,<ymin>,<xmax>,<ymax>: مرزهایی که مجموعه داده بر اساس آن‌ها برش داده می‌شود. فرض بر این است که این مقادیر در CRS مجموعه داده ورودی هستند، مگر اینکه --bbox-crs مشخص شده باشد. محورهای X و Y از نوع "سازگار با GIS" هستند؛ بدین صورت که X نشان‌دهنده طول جغرافیایی یا جهت خاوری (easting) و Y نشان‌دهنده عرض جغرافیایی یا جهت شمالی (northing) است. امکان استفاده هم‌زمان با --like و --geometry وجود ندارد.

--bbox-crs <CRS>: سامانه مرجع مختصاتی (CRS) که مقادیر <xmin>,<ymin>,<xmax>,<ymax> در گزینه --bbox بر حسب آن بیان شده‌اند. اگر تعیین نشود، فرض می‌شود که همان CRS مجموعه داده ورودی است. توجه داشته باشید که تعیین --bbox-crs شامل انجام بازتصویرسازی برداری نمی‌شود؛ بلکه مرزها از bbox-crs به CRS مجموعه داده ورودی بازتصویر می‌شوند.

--geometry <WKT_or_GeoJSON>: هندسه به صورت یک رشته با ساختار WKT یا GeoJSON که مجموعه داده بر اساس آن برش داده می‌شود. اگر هندسه ورودی GeoJSON باشد، CRS آن WGS84 فرض می‌شود، مگر اینکه یک CRS درون هندسه GeoJSON تعریف شده باشد یا گزینه --geometry-crs مشخص گردد. اگر هندسه ورودی WKT باشد، CRS آن همان CRS مجموعه داده ورودی لحاظ می‌شود، مگر اینکه --geometry-crs مشخص شده باشد. محورهای X و Y از نوع "سازگار با GIS" هستند؛ یعنی X طول جغرافیایی یا جهت خاوری (easting) و Y عرض جغرافیایی یا جهت شمالی (northing) است. امکان استفاده هم‌زمان با --bbox و --like وجود ندارد.

--geometry-crs <CRS>: سامانه مرجع مختصاتی (CRS) که مقادیر مختصات --geometry بر حسب آن بیان شده‌اند. اگر تعیین نشود، فرض می‌شود که همان CRS مجموعه داده ورودی است. توجه داشته باشید که تعیین --geometry-crs شامل انجام بازتصویرسازی برداری نمی‌شود؛ بلکه مرزها از geometry-crs به CRS مجموعه داده ورودی بازتصویر می‌شوند.

--like <DATASET>: مجموعه داده برداری یا شطرنجی (رستری) برای استفاده به عنوان الگو جهت تعیین مرزها. اگر مجموعه داده تعیین‌شده رستر باشد، مرزهای مستطیلی آن به عنوان هندسه برش استفاده خواهد شد. اگر مجموعه داده تعیین‌شده برداری باشد، هندسه‌های چندضلعی آن با یکدیگر ادغام (اجتماع) می‌شوند تا هندسه برش تشکیل شود (دقت داشته باشید در صورت وجود شکاف میان عوارض چندضلعی مجزا، اجتماع حاصل ممکن است کاملاً یکپارچه نباشد). در صورت وجود چندین لایه، باید --like-sql یا --like-layer مشخص گردد. امکان استفاده هم‌زمان با --bbox و --geometry وجود ندارد.

--like-layer <LAYER-NAME>: انتخاب لایه نام‌برده از مجموعه داده برداری برش. امکان استفاده هم‌زمان با --like-sql وجود ندارد.

--like-sql <SELECT-STATEMENT>: انتخاب هندسه‌های مورد نظر از مجموعه داده برداری برش با استفاده از یک پرس‌وجوی SQL. برای نمونه: SELECT geom FROM my_layer WHERE country = 'France'. امکان استفاده هم‌زمان با --like-layer و --like-where وجود ندارد.

--like-where <WHERE-EXPRESSION>: محدود کردن هندسه‌های مورد نظر از لایه مجموعه داده برداری برش بر پایه یک پرس‌وجوی توصیفی (ویژگی). برای نمونه: country = 'France'.

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

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

--co, --creation-option <NAME>=<VALUE>

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

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

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

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

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

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

--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-layer <NAME>: نام لایه‌ای را که عوارض در آن نوشته می‌شوند مشخص می‌کند. در صورت عدم تعیین، نام لایه‌های خروجی همانند نام لایه‌های ورودی خواهد بود.

--output-open-option, --output-oo <NAME>=<VALUE>

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

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

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

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

--overwrite-layer: مشخص می‌کند که آیا بازنویسی لایه برداری خروجیِ موجود مجاز است یا خیر.

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

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

--upsert

در نسخه 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 وجود داشته باشد که کلید اصلی عدد صحیح نباشد.

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

مثال‌ها (EXAMPLES)

مثال ۱: برش یک فایل GeoPackage به کادر احاطه‌کننده از طول جغرافیایی 2، عرض جغرافیایی 49 تا طول جغرافیایی 3، عرض جغرافیایی 50 در WGS 84

$ gdal vector clip --bbox=2,49,3,50 --bbox-crs=EPSG:4326 in.gpkg out.gpkg --overwrite

نویسندگان (AUTHORS)

Even Rouault <even.rouault@spatialys.com>

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

1998-2026

August 18, 2026