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] Calculate raster zonal statistics Positional arguments: -i, --input Input raster datasets [required] [not available in pipelines] -o, --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 = 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 ("GDALG" allowed) [not available in pipelines] --co, --creation-option = Creation option [may be repeated] [not available in pipelines] --lco, --layer-creation-option = 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 name [not available in pipelines] --skip-errors Skip errors when writing features [not available in pipelines] -b, --band Input band(s) (1-based index) [may be repeated] --zones Dataset containing zone definitions [required] --zones-band Band from which zones should be read Mutually exclusive with --zones-layer --zones-layer Layer from which zones should be read Mutually exclusive with --zones-band --weights Weighting raster dataset --weights-band Band from which weights should be read (default: 1) --pixels Method to determine which pixels are included in stat calculation.. PIXELS=default|fractional|all-touched --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 Fields from polygon zones to include in output [may be repeated] --include-geom Include polygon zone geometry in the output --strategy For polygon zones, whether to iterate over input features or raster chunks. STRATEGY=feature|raster (default: feature) --chunk-size Maximum size of raster chunks read into memory (default: 5%) Advanced Options: --if, --input-format Input formats [may be repeated] [not available in pipelines] --oo, --open-option = Open options [may be repeated] [not available in pipelines] --output-oo, --output-open-option = 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) مشخص شده‌اند. [تصویر] میانگین ارتفاع محاسبه‌شده برای هر چندضلعی از یک رستر ارتفاعی..UNINDENT می‌توان علاوه بر رستر مبدا، یک رستر وزن‌دهی نیز تعیین کرد که امکان محاسبه آمارهایی مانند میانگین شرایط آب‌وهوایی وزن‌دهی‌شده با جمعیت را فراهم می‌کند. تمامی ورودی‌ها باید در یک سیستم مرجع مکانی (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 باند(های) ورودی برای پردازش. --chunk-size حداکثر اندازه تکه‌های (Chunk) رستر را برای خواندن در حافظه مشخص می‌کند. می‌تواند به‌صورت مقدار حافظه (500 MB، 2 GB و غیره) یا به‌صورت درصدی از حافظه رم در دسترس (مثلاً 10%) بیان شود. --include-field یک یا چند فیلد از منطقه‌ها را برای کپی شدن در خروجی مشخص می‌کند. فقط هنگام استفاده از منطقه‌های برداری در دسترس است. از نسخه GDAL 3.13، می‌توان از مقادیر ویژه "ALL" و "NONE" استفاده کرد. --include-geom هندسه منطقه را در عارضه خروجی می‌گنجاند. فقط هنگام استفاده از منطقه‌های برداری در دسترس است. در نسخه 3.13 اضافه شد. --pixels روش تعیین اینکه کدام پیکسل‌ها باید در محاسبه لحاظ شوند: default، all-touched یا fractional. --stat یک یا چند مورد از آمارهای پشتیبانی‌شده را برای محاسبه در هر منطقه مشخص می‌کند. --strategy راهبرد پردازش (raster یا feature) را هنگام استفاده از منطقه‌های برداری مشخص می‌کند. در راهبرد پیش‌فرض (--strategy feature)، GDAL روی عوارض موجود در مجموعه‌داده منطقه پیمایش می‌کند، پیکسل‌های متناظر را از رستر می‌خواند و آمارهای آن عارضه را می‌نویسد. این کار مانع از نیاز به بارگذاری کل مجموعه‌داده عارضه به‌طور هم‌زمان در حافظه می‌شود، اما اگر عوارض چندضلعی بزرگ باشند یا از نظر مکانی مرتب نباشند، ممکن است باعث خواندن چندباره پیکسل‌های یکسان شود. اگر از --strategy raster استفاده شود، GDAL روی تکه‌های مجموعه‌داده رستر پیمایش می‌کند، منطقه‌های چندضلعی متناظر را می‌یابد و آمار آن عوارض را به‌روزرسانی می‌کند. (اندازه تکه‌های رستر را می‌توان با استفاده از --chunk-size کنترل کرد.) این تضمین می‌کند که پیکسل‌های رستر فقط یک بار خوانده شوند، اما ممکن است باعث پردازش چندباره عوارض یکسان شود. --weights مسیر اختیاری به مجموعه‌داده‌ای که برای وزن‌دهی استفاده می‌شود. --weights-band باند رستری را که وزن‌ها می‌توانند از آن خوانده شوند مشخص می‌کند. --zones مسیر به مجموعه‌داده‌ای که منطقه‌ها را تعریف می‌کند. اگر مجموعه‌داده دارای بیش از ۱ باند رستر یا لایه عارضه باشد، باید --zones-band یا --zones-layer مشخص شود. --zones-band باند رستری را که منطقه‌ها می‌توانند از آن خوانده شوند مشخص می‌کند. --zones-layer لایه عارضه‌ای را که منطقه‌ها می‌توانند از آن خوانده شوند مشخص می‌کند. گزینه‌های استاندارد (STANDARD OPTIONS) --append تعیین اینکه آیا الحاق عوارض به لایه(های) موجود مجاز است یا خیر. این گزینه در صورتی که مجموعه‌داده خروجی هنوز وجود نداشته باشد، آن را ایجاد می‌کند. --co, --creation-option = بسیاری از قالب‌ها یک یا چند گزینه اختیاری ایجاد مجموعه‌داده دارند که می‌توان از آن‌ها برای کنترل ویژگی‌های مربوط به فایل ایجادشده استفاده کرد. برای مثال، درایور GeoPackage از گزینه‌های ایجاد برای کنترل نسخه پشتیبانی می‌کند. می‌تواند تکرار شود. گزینه‌های ایجاد مجموعه‌داده بسته به درایور قالب متفاوت هستند، و برخی قالب‌های ساده اصلاً هیچ گزینه ایجادی ندارند. فهرستی از گزینه‌های پشتیبانی‌شده برای یک قالب را می‌توان با گزینه خط فرمان --formats مشاهده کرد، اما مستندات خود قالب منبع اصلی اطلاعات درباره گزینه‌های ایجاد درایور است. برای گزینه‌های مجاز ایجاد هر قالب، مستندات اختصاصی قالب Vector drivers را ببینید. توجه داشته باشید که گزینه‌های ایجاد مجموعه‌داده با گزینه‌های ایجاد لایه متفاوت هستند. --if, --input-format نام قالب/درایور برای تلاش جهت باز کردن فایل(های) ورودی. معمولاً نیازی به تعیین آن نیست، اما زمانی که تشخیص خودکار درایور در انتخاب درایور مناسب ناموفق باشد، می‌توان از آن برای چشم‌پوشی از تشخیص خودکار استفاده کرد. این گزینه می‌تواند چندین بار برای تعیین چندین درایور کاندید تکرار شود. توجه داشته باشید که این گزینه درایورها را مجبور به باز کردن مجموعه‌داده نمی‌کند؛ به‌ویژه برخی درایورها نیازمندی‌هایی برای پسوند فایل دارند. می‌تواند تکرار شود. --lco, --layer-creation-option = بسیاری از قالب‌ها یک یا چند گزینه اختیاری ایجاد لایه دارند که می‌توان از آن‌ها برای کنترل ویژگی‌های مربوط به لایه ایجادشده استفاده کرد. برای مثال، درایور GeoPackage از گزینه‌های ایجاد لایه برای کنترل شناسه عارضه یا نام ستون هندسه، تنظیم شناسه یا توضیحات و غیره پشتیبانی می‌کند. می‌تواند تکرار شود. گزینه‌های ایجاد لایه بسته به درایور قالب متفاوت هستند، و برخی قالب‌های ساده اصلاً هیچ گزینه ایجاد لایه‌ای ندارند. فهرستی از گزینه‌های پشتیبانی‌شده برای یک قالب را می‌توان با گزینه خط فرمان --formats مشاهده کرد، اما مستندات آن قالب منبع اصلی اطلاعات درباره گزینه‌های ایجاد لایه درایور است. برای گزینه‌های مجاز ایجاد لایه در هر قالب، مستندات اختصاصی قالب Vector drivers را ببینید. توجه داشته باشید که گزینه‌های ایجاد لایه با گزینه‌های ایجاد مجموعه‌داده متفاوت هستند. --oo, --open-option = گزینه باز کردن مجموعه‌داده (مختص هر قالب). می‌تواند تکرار شود. -f, --of, --format, --output-format تعیین اینکه کدام قالب برداری خروجی استفاده شود. مقادیر مجاز را می‌توان با دستور زیر به دست آورد: gdal --formats | grep vector | grep rw | sort --output-layer نام لایه‌ای را مشخص می‌کند که عوارض در آن نوشته خواهند شد. در صورت عدم تعیین، نام‌های لایه خروجی همانند نام‌های لایه ورودی خواهند بود. --output-open-option, --output-oo = در نسخه 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 حق نشر (COPYRIGHT) 1998-2026 August 18, 2026 GDAL-RASTER-ZONAL-STATS(1)