--calc

عبارتی که باید با استفاده از کتابخانه تحلیل‌گر ریاضی muparser ارزیابی شود. عبارت ممکن است به باندهای تکی هر ورودی ارجاع دهد (مثلاً X[1] + 3) یا ممکن است روی تمام باندهای یک ورودی اعمال شود (X + 3).

دو روش برای اعمال یک عبارت روی چندین باند وجود دارد. در روش پیش‌فرض، عبارت روی هر باند به صورت جداگانه اعمال می‌شود که نتیجه آن یک باند خروجی به ازای هر باند ورودی است. برای مثال، با یک ورودی سه‌بانده X، عبارت --calc "X+3" به --calc "X[1]+3" --calc "X[2]+3" --calc "X[3]+3" بسط داده می‌شود. اگر عبارت شامل ارجاع به تمام باندهای چندین ورودی باشد، آن ورودی‌ها یا باید تعداد باندهای یکسانی داشته باشند، یا یک تک‌باند باشند. برای مثال، اگر ورودی‌های A و B هر کدام سه باند داشته باشند، و ورودی C یک تک‌باند داشته باشد، در این صورت آرگومان --calc "A + B + C" معادل است با --calc "A[1] + B[1] + C[1]" --calc "A[2] + B[2] + C[1]" --calc "A[3] + B[3] + C[1]". به طور مشابه، --calc "sum(A,B,C)" به صورت زیر بسط می‌یابد: --calc "sum(A[1], B[1], C[1]" --calc "sum(A[2], B[2], C[1])" --calc "sum(A[3], B[3], C[1])".

در روش دوم، که با --flatten فعال می‌شود، توابع تجمیعی (sum، avg، min و max) فراخوانی‌شده روی چندین باند، به صورت تجمیعی روی همه باندها اعمال خواهند شد. در این حالت، sum(A) به sum(A[1], A[2], A[3]) و sum(A,C) به sum(A[1], A[2], A[3], C[1]) بسط می‌یابد. اگر عبارت _تنها_ از توابع تجمیعی تشکیل شده باشد، صرف‌نظر از تعداد باندهای ورودی، یک باند خروجی تکی تولید خواهد شد. با این حال، اگر عبارت حاوی یک ارجاع غیرتجمیعی به تمام باندهای یک ورودی باشد، آن‌گاه همچنان به ازای هر باند ورودی، یک باند خروجی تولید خواهد شد. یک نمونه ساده، عبارت A / sum(A) است که یک رستر N-بانده تولید می‌کند که در آن هر باند خروجی، سهم باند ورودی از مجموع کل را شامل می‌شود.

می‌توان چندین محاسبه را مشخص کرد؛ باند(های) خروجی به ازای هر عبارت و به ترتیبی که ارائه شده‌اند، تولید خواهند شد.

رسترهای ورودی پیش از انجام محاسبات به اعداد ممیز شناور ۶۴ بیتی تبدیل خواهند شد.

از GDAL 3.12 به بعد، همچنین می‌توان با تعیین --dialect بر روی builtin، از یک تابع پیکسلی C++ در VRT (مانند sum، mean، min، max) استفاده کرد. آرگومان‌های توابع در داخل پرانتز ارسال می‌شوند، مانند sum(k=1)، min(propagateNoData=true) یا interpolate_linear(t0=1,dt=1,t=10)..SS "متغیرهای توکار (Built-in variables)"

متغیرهای توکار زیر در عبارت‌ها در دسترس هستند:

این متغیرها برای محاسباتی که به موقعیت مکانی وابسته هستند مفیدند، مانند تصحیحات مبتنی بر عرض جغرافیایی، تقریب زاویه تابش خورشید، یا ماسک‌های منطقه‌ای.

برای مشاهده یک نمونه کاربرد، Example 7 را ببینید.

نکته: برای کار با مقادیر طول/عرض جغرافیایی، مجموعه‌داده ورودی باید در یک سامانه مرجع مختصات جغرافیایی (برای نمونه EPSG:4326) باشد.

--dialect muparser|builtin

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

موتور عبارتی را که برای تفسیر مقدار --calc استفاده می‌شود مشخص می‌کند. پیش‌فرض muparser است.

--flatten

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

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

برای گویش پیش‌فرض muparser، استفاده از نام یک رستر ورودی (برای نمونه A) معادل با A[1],A[2],...,A[n] است. چنین ساختاری با توابع min، max، sum و avg در muparser کار می‌کند.

برای نمونه، اگر دو رستر A و B را با ۳ باند برای هر کدام در نظر بگیریم، آنگاه --flatten --calc "avg(A)-avg(B)" معادل خواهد بود با --calc "avg(A[1],A[2],A[3])-avg(B[1],B[2],B[3])"

و دستور --flatten --dialect=builtin --calc mean یک تک‌باند را با میانگین تمام ۴ باند ورودی محاسبه خواهد کرد.

-i [<name>=]<input>

یک مجموعه‌داده ورودی را برای پردازش انتخاب می‌کند. اگر بیش از یک مجموعه‌داده ورودی مشخص شود، پیش از هر مجموعه‌داده باید نامی قرار گیرد که در --calc به آن ارجاع داده خواهد شد.

--no-check-extent

بررسی نمی‌کند که رسترهای ورودی وسعت مکانی یکسانی دارند یا خیر. در عوض لازم است رسترهای ورودی ابعاد یکسانی داشته باشند. زمین‌مرجع (geotransform) اولین ورودی به خروجی اختصاص داده خواهد شد.

--no-check-crs

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

--nodata

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

مقدار NoData را برای مجموعه‌داده خروجی تنظیم می‌کند. می‌تواند برابر "none" قرار گیرد تا مقدار NoData تعریف‌نشده باقی بماند. اگر --nodata مشخص نشود، gdal raster calc از مقدار NoData اولین مجموعه‌داده مبدأ که دارای آن باشد استفاده خواهد کرد.

--propagate-nodata

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

در صورت تنظیم، وجود مقدار NoData در هر مجموعه‌داده ورودیِ استفاده‌شده در عبارت، باعث می‌شود که مقدار خروجی NoData گردد.

--append

رستر ورودی را به عنوان یک زیرمجموعه‌داده (subdataset) جدید به یک فایل خروجیِ موجود اضافه (الحاق) می‌کند. تنها با درایورهایی کار می‌کند که از افزودن زیرمجموعه‌داده‌ها پشتیبانی می‌کنند، مانند GTiff -- GeoTIFF File Format و GPKG -- GeoPackage raster. این گزینه همچنین مجموعه‌داده خروجی را در صورتی که از قبل وجود نداشته باشد ایجاد می‌کند.

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

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

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

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

--if, --input-format <format>

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

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

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

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

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

-f, --of, --format, --output-format <OUTPUT-FORMAT>

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

--ot, --datatype, --output-data-type <OUTPUT-DATA-TYPE>

نوع داده خروجی از میان Byte، Int8، UInt16، Int16، UInt32، Int32، UInt64، Int64، CInt16، CInt32، Float32، Float64، CFloat32، CFloat64.

--overwrite

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

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