نام (NAME)

gdal-raster-clip - برش دادن یک مجموعه داده رستر

افزوده‌شده در نگارش 3.11.

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

کاربرد: gdal raster clip [گزینه‌ها] <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>                گزینه ایجاد [تکرارپذیر] [در خطوط لوله در دسترس نیست]
  --overwrite                                          آیا رونویسی روی مجموعه داده خروجی موجود مجاز است [در خطوط لوله در دسترس نیست]
                                                       ناسازگار با --append
  --append                                             افزودن به عنوان زیرمجموعه‌داده به خروجی موجود [در خطوط لوله در دسترس نیست]
                                                       ناسازگار با --overwrite
  --bbox <BBOX>                                        جعبه محدودکننده برش به صورت xmin,ymin,xmax,ymax
                                                       ناسازگار با --window، --geometry، --like
  --bbox-crs <BBOX-CRS>                                سامانه مرجع مختصات (CRS) برای جعبه محدودکننده برش
  --window <WINDOW>                                    پنجره رستر به صورت col,line,width,height بر حسب پیکسل
                                                       ناسازگار با --bbox، --geometry، --like
  --geometry <GEOMETRY>                                هندسه برش (WKT یا GeoJSON)
                                                       ناسازگار با --bbox، --window، --like
  --geometry-crs <GEOMETRY-CRS>                        سامانه مرجع مختصات (CRS) هندسه برش
  --like <DATASET>                                     مجموعه داده برای استفاده به عنوان الگو برای محدوده‌ها
                                                       ناسازگار با --bbox، --window، --geometry
  --like-sql <SELECT-STATEMENT>                        عبارت SELECT برای اجرا روی مجموعه داده 'like'
                                                       ناسازگار با --like-where
  --like-layer <LAYER-NAME>                            نام لایه از مجموعه داده 'like'
  --like-where <WHERE-EXPRESSION>                      بند WHERE در SQL برای اجرا روی مجموعه داده 'like'
                                                       ناسازگار با --like-sql
  --only-bbox                                          برای 'geometry' و 'like'، فقط جعبه محدودکننده در نظر گرفته شود
  --allow-bbox-outside-source                          اجازه دادن به جعبه برش جهت در بر گرفتن پیکسل‌های خارج از مجموعه داده ورودی
  --add-alpha                                          افزودن یک باند ماسک آلفا به مقصد در صورتی که رستر مبدأ فاقد آن باشد.
گزینه‌های پیشرفته:
  --if, --input-format <INPUT-FORMAT>                  قالب‌های ورودی [تکرارپذیر] [در خطوط لوله در دسترس نیست]
  --oo, --open-option <KEY>=<VALUE>                    گزینه‌های باز کردن [تکرارپذیر] [در خطوط لوله در دسترس نیست]

توضیحات (DESCRIPTION)

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

باید حداقل یکی از گزینه‌های --bbox یا --like مشخص شود.

مجموعه داده خروجی در همان SRS مجموعه داده ورودی خواهد بود و وضوح (resolution) اصلی حفظ می‌شود. محدوده‌ها برای تطابق با موقعیت‌های کامل پیکسل گرد می‌شوند (به این معنی که هیچ بازنمونه‌گیری یا resampling انجام نمی‌شود).

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

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

--add-alpha: افزودن یک باند ماسک آلفا به مقصد در صورتی که رستر مبدأ فاقد آن باشد.

--allow-bbox-outside-source: در صورت تنظیم، اجازه می‌دهد محدوده‌های تعیین‌شده توسط --bbox وسعتی فراتر از مجموعه داده ورودی را پوشش دهند. پیکسل‌های خروجی در نواحی خارج از وسعت ورودی برابر با صفر یا مقدار NoData مجموعه داده ورودی تنظیم خواهند شد.

--bbox <xmin>,<ymin>,<xmax>,<ymax>: محدوده‌هایی که مجموعه داده باید بر اساس آن‌ها برش داده شود. فرض می‌شود که این مختصات در CRS مجموعه داده ورودی هستند، مگر آنکه --bbox-crs مشخص شده باشد. محورهای X و Y بر اساس محورهای مرسوم در GIS هستند، به این معنی که X طول جغرافیایی (یا مختصات شرقی) و Y عرض جغرافیایی (یا مختصات شمالی) است. در صورت نیاز، محدوده‌ها برای تطابق با مرزهای پیکسل ورودی بسط داده می‌شوند. به صورت پیش‌فرض، اگر محدوده‌های تعیین‌شده با --bbox بزرگ‌تر از وسعت مجموعه داده ورودی باشند، gdal raster clip با خطا متوقف می‌شود. با استفاده از --allow-bbox-outside-source می‌توان از این بررسی صرف‌نظر کرد.

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

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

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

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

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

--like-sql <SELECT-STATEMENT>: انتخاب هندسه‌های مورد نظر از مجموعه داده برش برداری با استفاده از یک پرسمان SQL. مانند SELECT geom FROM my_layer WHERE country = 'France'. گویش SQL مورد استفاده، گویش پیش‌فرض مجموعه داده like خواهد بود (OGR SQL برای Shapefile، و SQLite برای GeoPackage، و PostgreSQL برای PostGIS و غیره). ناسازگار با --like-layer و --like-where.

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

--only-bbox: برای گزینه‌های --geometry و --like، تنها جعبه محدودکننده هندسه در نظر گرفته شود.

--window <column>,<line>,<width>,<height>: افزوده‌شده در نگارش 3.12.
انتخاب یک زیرپنجره از تصویر مبدأ برای کپی کردن بر اساس موقعیت پیکسل/سطر. فاصله‌های پیکسل/سطر (column و line) از سمت چپ و بالای تصویر سنجیده می‌شوند. اگر زیرپنجره به خارج از محدوده‌های مجموعه داده مبدأ امتداد یابد، پیکسل‌های خروجی با مقدار صفر نوشته خواهند شد، مگر اینکه مقدار NoData در مجموعه داده مبدأ تعریف شده باشد.

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

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

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

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

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

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

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

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

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

کد وضعیت بازگشتی (RETURN STATUS CODE)

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

مثال‌ها (EXAMPLES)

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

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

مثال ۲: برش دادن یک فایل GeoTIFF با استفاده از محدوده‌های reference.tif

$ gdal raster clip --like=reference.tif in.tif out.tif --overwrite

مثال ۳: برش دادن یک فایل GeoTIFF از ستون رستر 1000 و سطر 2000، با عرض 500 پیکسل و ارتفاع 600 پیکسل

$ gdal raster clip --window=1000,2000,500,600 in.tif out.tif --overwrite

مثال ۴: برش دادن یک GeoTIFF با استفاده از یک جعبه محدودکننده که فراتر از وسعت مبدأ امتداد دارد و نوشتن نتیجه به عنوان یک COG

استفاده از --allow-bbox-outside-source برای جلوگیری از خطای ERROR 1: Computed source window -180 2943 6269 6235 falls partially outside source raster extent هنگامی که جعبه محدودکننده از وسعت رستر فراتر می‌رود.

$ gdal raster clip \
    --bbox=3757032.814272985,-626172.1357121654,4383204.9499851465,0 \
    --bbox-crs=EPSG:3857 \
    --allow-bbox-outside-source \
    in.tif out.tif \
    --overwrite \
    --output-format COG

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

Even Rouault <even.rouault@spatialys.com>

حق نشر (COPYRIGHT)

1998-2026

August 18, 2026