| GDAL-RASTER-ZONAL-STATS(1) | GDAL | GDAL-RASTER-ZONAL-STATS(1) |
نام (NAME)
gdal-raster-zonal-stats - محاسبه آمارهای منطقه‌ای رستر
در نسخه 3.12 اضافه شد.
خلاصه دستور (SYNOPSIS)
Usage: gdal raster zonal-stats [OPTIONS] <INPUT> <OUTPUT>
Calculate raster zonal statistics
Positional arguments:
-i, --input <INPUT> Input raster 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:
-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]
-b, --band <BAND> Input band(s) (1-based index) [may be repeated]
--zones <ZONES> Dataset containing zone definitions [required]
--zones-band <ZONES-BAND> Band from which zones should be read
Mutually exclusive with --zones-layer
--zones-layer <ZONES-LAYER> Layer from which zones should be read
Mutually exclusive with --zones-band
--weights <WEIGHTS> Weighting raster dataset
--weights-band <WEIGHTS-BAND> Band from which weights should be read (default: 1)
--pixels <PIXELS> Method to determine which pixels are included in stat calculation.. PIXELS=default|fractional|all-touched
--stat <STAT> Statistic(s) to compute for each zone. STAT=center_x|center_y|count|coverage|frac|max|max_center_x|max_center_y|mean|median|min|minority|min_center_x|min_center_y|mode|stdev|sum|unique|values|variance|variety|weighted_mean|weighted_stdev|weighted_sum|weighted_variance|weights [may be repeated] [required]
--include-field <INCLUDE-FIELD> Fields from polygon zones to include in output [may be repeated]
--include-geom Include polygon zone geometry in the output
--strategy <STRATEGY> For polygon zones, whether to iterate over input features or raster chunks. STRATEGY=feature|raster (default: feature)
--chunk-size <CHUNK-SIZE> Maximum size of raster chunks read into memory (default: 5%)
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
توضیحات (DESCRIPTION)
دستور gdal raster zonal-stats آمارهای منطقه‌ای رستر (Zonal Statistics) را محاسبه می‌کند -- خلاصه‌ای از مقادیر پیکسل‌ها درون منطقه‌هایی که با عوارض چندضلعی (پلی‌گون) یا یک رستر دسته‌بندی‌شده (Categorical) مشخص شده‌اند.
می‌توان علاوه بر رستر مبدا، یک رستر وزن‌دهی نیز تعیین کرد که امکان محاسبه آمارهایی مانند میانگین شرایط آب‌وهوایی وزن‌دهی‌شده با جمعیت را فراهم می‌کند.
تمامی ورودی‌ها باید در یک سیستم مرجع مکانی (CRS) یکسان ارائه شوند. اگر رسترهای ورودی دارای تفکیک‌پذیری‌های متفاوتی باشند، با استفاده از بازنمونه‌برداری میانگین به یک تفکیک‌پذیری یکپارچه تغییر مقیاس می‌یابند. با این حال، هیچ بازتصویرسازی (Reprojection) انجام نمی‌شود.
دربرگیری پیکسل‌ها و وزن‌دهی (Pixel inclusion and weighting)
هنگامی که منطقه‌ها با استفاده از چندضلعی‌ها تعریف می‌شوند، سه روش برای تعیین اینکه کدام پیکسل‌ها در محاسبه لحاظ شوند در دسترس است. به‌طور پیش‌فرض، هندسه‌ها با استفاده از پارامترهای پیش‌فرض رسترایز (پیکسلی) می‌شوند و پیکسل‌های موجود در رسترایز با وزن یکسان در محاسبه به کار می‌روند. با استفاده از --pixels all-touched، تمامی پیکسل‌هایی که با چندضلعی تماس دارند در محاسبه لحاظ می‌شوند، باز هم با وزن یکسان. اگر از --pixels fractional استفاده شود، کسری از هر پیکسل که توسط چندضلعی پوشش داده شده است محاسبه می‌شود و پیکسل‌ها بر اساس این کسر وزن‌دهی می‌شوند. این گزینه نیازمند این است که GDAL با نسخه 3.14 یا بالاتر از کتابخانه GEOS ساخته شده باشد.
آمارهای پشتیبانی‌شده (Supported stats)
| نام | توضیحات |
| center_x | آرایه‌ای شامل مختصات x مرکز سلول برای هر سلولی که با چندضلعی تقاطع دارد. مرکز هر سلول ممکن است درون چندضلعی باشد یا نباشد. |
| center_y | آرایه‌ای شامل مختصات y مرکز سلول برای هر سلولی که با چندضلعی تقاطع دارد. مرکز هر سلول ممکن است درون چندضلعی باشد یا نباشد. |
| count | مجموع تمامی کسرهای پوشش سلول‌ها. |
| coverage | آرایه‌ای شامل کسر پوشش هر سلولی که با چندضلعی تقاطع دارد. |
| frac | کسری از سلول‌های پوشش‌داده‌شده که توسط هر مقدار متمایز رستر اشغال شده‌اند، همان‌طور که توسط unique ارائه می‌شود. |
| max | بیشترین مقدار سلول‌هایی که با چندضلعی تقاطع دارند، بدون در نظر گرفتن کسرهای پوشش یا مقادیر رستر وزن‌دهی. |
| max_center_x | مختصات x مرکز سلول برای سلول حاوی بیشترین مقدار که با چندضلعی تقاطع دارد. مرکز این سلول ممکن است درون چندضلعی باشد یا نباشد. |
| max_center_y | مختصات y مرکز سلول برای سلول حاوی بیشترین مقدار که با چندضلعی تقاطع دارد. مرکز این سلول ممکن است درون چندضلعی باشد یا نباشد. |
| mean | مقدار میانگین سلول‌هایی که با چندضلعی تقاطع دارند، وزن‌دهی‌شده بر اساس درصد پوشش هر سلول. |
| min | کمترین مقدار سلول‌هایی که با چندضلعی تقاطع دارند، بدون در نظر گرفتن کسرهای پوشش یا مقادیر رستر وزن‌دهی. |
| min_center_x | مختصات x مرکز سلول برای سلول حاوی کمترین مقدار که با چندضلعی تقاطع دارد. مرکز این سلول ممکن است درون چندضلعی باشد یا نباشد. |
| min_center_y | مختصات y مرکز سلول برای سلول حاوی کمترین مقدار که با چندضلعی تقاطع دارد. مرکز این سلول ممکن است درون چندضلعی باشد یا نباشد. |
| minority | مقدار رستری که کمترین تعداد سلول را اشغال کرده است، با در نظر گرفتن کسرهای پوشش سلول اما بدون لحاظ مقادیر رستر وزن‌دهی. |
| mode | مقدار رستری که بیشترین تعداد سلول را اشغال کرده است (مد/نما)، با در نظر گرفتن کسرهای پوشش سلول اما بدون لحاظ مقادیر رستر وزن‌دهی. |
| stdev | انحراف معیار جامعه برای مقادیر سلول‌هایی که با چندضلعی تقاطع دارند، با در نظر گرفتن کسر پوشش. |
| sum | مجموع مقادیر سلول‌های رستر که با چندضلعی تقاطع دارند، که در آن هر مقدار رستر بر اساس کسر پوشش خود وزن‌دهی می‌شود. |
| unique | آرایه‌ای از مقادیر یکتای رستر برای سلول‌هایی که با چندضلعی تقاطع دارند. |
| values | آرایه‌ای از مقادیر رستر برای هر سلولی که با چندضلعی تقاطع دارد. |
| variance | واریانس جامعه برای مقادیر سلول‌هایی که با چندضلعی تقاطع دارند، با در نظر گرفتن کسر پوشش. |
| variety | تعداد مقادیر متمایز رستر در سلول‌هایی که به‌طور کامل یا جزئی توسط چندضلعی پوشش داده شده‌اند. |
| weighted_frac | کسری از سلول‌های پوشش‌داده‌شده که توسط هر مقدار متمایز رستر اشغال شده‌اند، وزن‌دهی‌شده با مقدار رستر وزن‌دهی دوم. ترتیب با مقادیر بازگردانده‌شده توسط unique مطابقت دارد. |
| weighted_mean | مقدار میانگین سلول‌هایی که با چندضلعی تقاطع دارند، وزن‌دهی‌شده با حاصل‌ضرب کسر پوشش و رستر وزن‌دهی. |
| weighted_stdev | نسخه وزن‌دهی‌شده stdev. |
| weighted_variance | نسخه وزن‌دهی‌شده variance |
| weights | آرایه‌ای از مقادیر وزن برای هر سلولی که با چندضلعی تقاطع دارد. |
این الگوریتم می‌تواند بخشی از یک gdal pipeline باشد.
گزینه‌های ویژه برنامه (PROGRAM-SPECIFIC OPTIONS)
- --band, -b <BAND>
- باند(های) ورودی برای پردازش.
- --chunk-size <MEMORY>
- حداکثر اندازه تکه‌های (Chunk) رستر را برای خواندن در حافظه مشخص می‌کند. می‌تواند به‌صورت مقدار حافظه (500 MB، 2 GB و غیره) یا به‌صورت درصدی از حافظه رم در دسترس (مثلاً 10%) بیان شود.
- --include-field <INCLUDE-FIELD>
- یک یا چند فیلد از منطقه‌ها را برای کپی شدن در خروجی مشخص می‌کند. فقط هنگام استفاده از منطقه‌های برداری در دسترس است. از نسخه GDAL 3.13، می‌توان از مقادیر ویژه "ALL" و "NONE" استفاده کرد.
- --include-geom
- هندسه
منطقه را در
عارضه
خروجی
می‌گنجاند.
فقط هنگام
استفاده از
منطقه‌های
برداری در
دسترس است.
در نسخه 3.13 اضافه شد.
- --pixels <PIXELS>
- روش تعیین اینکه کدام پیکسل‌ها باید در محاسبه لحاظ شوند: default، all-touched یا fractional.
- --stat <STAT>
- یک یا چند مورد از آمارهای پشتیبانی‌شده را برای محاسبه در هر منطقه مشخص می‌کند.
- --strategy <STRATEGY>
- راهبرد پردازش (raster یا feature) را هنگام استفاده از منطقه‌های برداری مشخص می‌کند. در راهبرد پیش‌فرض (--strategy feature)، GDAL روی عوارض موجود در مجموعه‌داده منطقه پیمایش می‌کند، پیکسل‌های متناظر را از رستر می‌خواند و آمارهای آن عارضه را می‌نویسد. این کار مانع از نیاز به بارگذاری کل مجموعه‌داده عارضه به‌طور هم‌زمان در حافظه می‌شود، اما اگر عوارض چندضلعی بزرگ باشند یا از نظر مکانی مرتب نباشند، ممکن است باعث خواندن چندباره پیکسل‌های یکسان شود. اگر از --strategy raster استفاده شود، GDAL روی تکه‌های مجموعه‌داده رستر پیمایش می‌کند، منطقه‌های چندضلعی متناظر را می‌یابد و آمار آن عوارض را به‌روزرسانی می‌کند. (اندازه تکه‌های رستر را می‌توان با استفاده از --chunk-size کنترل کرد.) این تضمین می‌کند که پیکسل‌های رستر فقط یک بار خوانده شوند، اما ممکن است باعث پردازش چندباره عوارض یکسان شود.
- --weights <WEIGHTS>
- مسیر اختیاری به مجموعه‌داده‌ای که برای وزن‌دهی استفاده می‌شود.
- --weights-band <WEIGHTS-BAND>
- باند رستری را که وزن‌ها می‌توانند از آن خوانده شوند مشخص می‌کند.
- --zones <ZONES>
- مسیر به مجموعه‌داده‌ای که منطقه‌ها را تعریف می‌کند. اگر مجموعه‌داده دارای بیش از ۱ باند رستر یا لایه عارضه باشد، باید --zones-band یا --zones-layer مشخص شود.
- --zones-band <ZONES-BAND>
- باند رستری را که منطقه‌ها می‌توانند از آن خوانده شوند مشخص می‌کند.
- --zones-layer <ZONES-LAYER>
- لایه عارضه‌ای را که منطقه‌ها می‌توانند از آن خوانده شوند مشخص می‌کند.
گزینه‌های استاندارد (STANDARD OPTIONS)
- --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-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::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)
مثال ۱: خلاصه‌سازی میانگین ارتفاع در فاصله ۲۰۰ متری از نقاط مورد نظر
استفاده از یک خط لوله تو در تو برای مجموعه‌داده منطقه:
gdal pipeline read dem.tif ! \
zonal-stats \
--zones [ read points.geojson ! buffer 200 ] \
--stat mean ! \
write \
--output-format CSV \
--output /vsistdout/
یا استفاده از مجموعه‌داده برداری منطقه به‌عنوان مجموعه‌داده منتقل‌شده با لوله با نام جایگزین ``_PIPE_``:
gdal pipeline read points.geojson ! \
buffer 200 ! \
zonal-stats \
--input dem.tif
--zones _PIPE_ \
--stat mean ! \
write \
--output-format CSV \
--output /vsistdout/
مثال ۲: ایجاد یک لایه با مرتفع‌ترین نقاط در هر حوزه آبخیز
gdal pipeline read dem.tif !
zonal-stats \
--zones watersheds.shp \
--stat max_center_x \
--stat max_center_y ! \
make-point \
--x max_center_x \
--y max_center_y \
--output-crs EPSG:4326 ! \
write out.geojson
نویسنده (AUTHOR)
Dan Baston <dbaston@gmail.com>
حق نشر (COPYRIGHT)
1998-2026
| August 18, 2026 |