.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "GDAL-RASTER-CALC" "1" "Aug 18, 2026" "" "GDAL" .SH "نام (NAME)" gdal-raster-calc \- انجام محاسبات پیکسل‌به‌پیکسل روی یک رستر .sp اضافه‌شده در نسخه 3.11. .SH "خلاصه دستور (SYNOPSIS)" .INDENT 0.0 .INDENT 3.5 .sp .EX Usage: gdal raster calc [OPTIONS] ... انجام جبر رستری Positional arguments: \-i, \-\-input مجموعه‌داده‌های رستری ورودی [۱.. مقدار] [الزامی] [در خط‌لوله‌ها در دسترس نیست] \-o, \-\-output مجموعه‌داده رستری خروجی [الزامی] [در خط‌لوله‌ها در دسترس نیست] Common Options: \-h, \-\-help نمایش پیام راهنما و خروج \-\-json\-usage نمایش نحوه استفاده به صورت سند JSON و خروج \-\-config = گزینه پیکربندی [می‌تواند تکرار شود] \-q, \-\-quiet حالت بی‌صدا (بدون نوار پیشرفت یا پیام هشدار) [در خط‌لوله‌ها در دسترس نیست] Options: \-f, \-\-of, \-\-format, \-\-output\-format قالب خروجی (\(dqGDALG\(dq مجاز است) [در خط‌لوله‌ها در دسترس نیست] \-\-co, \-\-creation\-option = گزینه ساخت [می‌تواند تکرار شود] [در خط‌لوله‌ها در دسترس نیست] \-\-overwrite تعیین مجاز بودن بازنویسی مجموعه‌داده خروجی موجود [در خط‌لوله‌ها در دسترس نیست] ناسازگار با \-\-append \-\-append الحاق به عنوان زیرمجموعه‌داده به خروجی موجود [در خط‌لوله‌ها در دسترس نیست] ناسازگار با \-\-overwrite \-\-ot, \-\-datatype, \-\-output\-data\-type نوع داده خروجی. OUTPUT\-DATA\-TYPE=UInt8|Int8|UInt16|Int16|UInt32|Int32|UInt64|Int64|CInt16|CInt32|Float16|Float32|Float64|CFloat32|CFloat64 \-\-no\-check\-crs عدم بررسی سازگاری و یکنواختی سیستم‌های مختصات مرجع ورودی \-\-no\-check\-extent عدم بررسی سازگاری گستره‌های مکانی ورودی \-\-propagate\-nodata تنظیم پیکسل‌ها به مقدار NoData خروجی در صورت NoData بودن هر یک از پیکسل‌های ورودی \-\-calc عبارت(ها) برای ارزیابی [۱.. مقدار] [الزامی] \-\-dialect گویش عبارت. DIALECT=muparser|builtin (پیش‌فرض: muparser) \-\-flatten ایجاد یک رستر خروجی تک‌بانده برای هر عبارت، حتی اگر مجموعه‌داده‌های ورودی چندبانده باشند \-\-nodata اختصاص مقدار nodata مشخص‌شده به باندهای خروجی (\(aqnone\(aq، مقدار عددی، \(aqnan\(aq، \(aqinf\(aq، \(aq\-inf\(aq) Advanced Options: \-\-if, \-\-input\-format قالب‌های ورودی [می‌تواند تکرار شود] [در خط‌لوله‌ها در دسترس نیست] \-\-oo, \-\-open\-option = گزینه‌های باز کردن [می‌تواند تکرار شود] [در خط‌لوله‌ها در دسترس نیست] .EE .UNINDENT .UNINDENT .SH "توضیحات (DESCRIPTION)" .sp دستور \fBgdal raster calc\fP محاسبات پیکسل‌به‌پیکسل را روی یک یا چند مجموعه‌داده ورودی GDAL انجام می‌دهد. محاسبات می‌توانند به صورت مشتاقانه (eager) انجام شده و نتایج در یک قالب رستری متداول نوشته شوند، یا به صورت با‌تأخیر (lazy) به عنوان مجموعه‌ای از باندهای مشتق‌شده در یک \fI\%VRT (Virtual Dataset)\fP\& نوشته شوند. .sp فهرست مجموعه‌داده‌های ورودی GDAL می‌تواند در انتهای خط فرمان مشخص شود یا برای فهرست‌های بسیار طولانی، درون یک فایل متنی (هر ورودی در یک خط) قرار گیرد. اگر بیش از یک مجموعه‌داده ورودی استفاده شود، باید پیشوندی از یک نام داشته باشد که در محاسبات با آن ارجاع داده خواهد شد؛ برای نمونه \fBA=my_data.tif\fP\&. (اگر یک مجموعه‌داده تکی استفاده شود، در فرمول‌ها با متغیر \fBX\fP به آن ارجاع داده می‌شود.) .sp از GDAL 3.12 به بعد، همچنین می‌توان با تنظیم \fI\%\-\-dialect\fP بر روی \fBbuiltin\fP\&، از یک \fI\%تابع پیکسلی C++ در VRT\fP (مانند \fBsum\fP، \fBmean\fP، \fBmin\fP، \fBmax\fP) استفاده کرد. .sp ورودی‌ها باید دارای سیستم مرجع مکانی یکسان باشند و گستره مکانی یکسانی را پوشش دهند، اما الزامی نیست که تفکیک‌پذیری مکانی یکسانی داشته باشند. بررسی گستره مکانی را می‌توان با \fI\%\-\-no\-check\-extent\fP غیرفعال کرد که در این صورت ابعاد ورودی‌ها باید یکسان باشد. بررسی سیستم مرجع مکانی را نیز می‌توان با \fI\%\-\-no\-check\-crs\fP\& غیرفعال کرد. .sp از GDAL 3.12، این الگوریتم می‌تواند بخشی از یک \fI\%gdal pipeline\fP یا \fI\%gdal raster pipeline\fP\& باشد. .SH "خروجی GDALG (مجموعه‌داده درلحظه / جریانی) (GDALG OUTPUT (ON-THE-FLY / STREAMED DATASET))" .sp این برنامه از سریال‌سازی خط فرمان به عنوان یک فایل JSON با استفاده از قالب خروجی \fBGDALG\fP پشتیبانی می‌کند. فایل حاصل را می‌توان سپس با استفاده از درایور \fI\%GDALG: GDAL Streamed Algorithm\fP به عنوان یک مجموعه‌داده رستری باز کرد، و خط‌لوله مشخص‌شده را به صورت درلحظه (on\-the\-fly) یا جریانی اعمال نمود. .SH "گزینه‌های ویژه برنامه (PROGRAM-SPECIFIC OPTIONS)" .INDENT 0.0 .TP .B \-\-calc عبارتی که باید با استفاده از کتابخانه تحلیل‌گر ریاضی \X'tty: link https://beltoforion.de/en/muparser'\fI\%muparser\fP\X'tty: link' ارزیابی شود. عبارت ممکن است به باندهای تکی هر ورودی ارجاع دهد (مثلاً \fBX[1] + 3\fP) یا ممکن است روی تمام باندهای یک ورودی اعمال شود (\fBX + 3\fP). .sp دو روش برای اعمال یک عبارت روی چندین باند وجود دارد. در روش پیش‌فرض، عبارت روی هر باند به صورت جداگانه اعمال می‌شود که نتیجه آن یک باند خروجی به ازای هر باند ورودی است. برای مثال، با یک ورودی سه‌بانده \fBX\fP، عبارت \fB\-\-calc \(dqX+3\(dq\fP به \fB\-\-calc \(dqX[1]+3\(dq \-\-calc \(dqX[2]+3\(dq \-\-calc \(dqX[3]+3\(dq\fP بسط داده می‌شود\&. اگر عبارت شامل ارجاع به تمام باندهای چندین ورودی باشد، آن ورودی‌ها یا باید تعداد باندهای یکسانی داشته باشند، یا یک تک‌باند باشند. برای مثال، اگر ورودی‌های \fBA\fP و \fBB\fP هر کدام سه باند داشته باشند، و ورودی \fBC\fP یک تک‌باند داشته باشد، در این صورت آرگومان \fB\-\-calc \(dqA + B + C\(dq\fP معادل است با \fB\-\-calc \(dqA[1] + B[1] + C[1]\(dq \-\-calc \(dqA[2] + B[2] + C[1]\(dq \-\-calc \(dqA[3] + B[3] + C[1]\(dq\fP\&. به طور مشابه، \fB\-\-calc \(dqsum(A,B,C)\(dq\fP به صورت زیر بسط می‌یابد: \fB\-\-calc \(dqsum(A[1], B[1], C[1]\(dq \-\-calc \(dqsum(A[2], B[2], C[1])\(dq \-\-calc \(dqsum(A[3], B[3], C[1])\(dq\fP\&. .sp در روش دوم، که با \fI\%\-\-flatten\fP فعال می‌شود، توابع تجمیعی (\fBsum\fP، \fBavg\fP، \fBmin\fP و \fBmax\fP) فراخوانی‌شده روی چندین باند، به صورت تجمیعی روی همه باندها اعمال خواهند شد. در این حالت، \fBsum(A)\fP به \fBsum(A[1], A[2], A[3])\fP و \fBsum(A,C)\fP به \fBsum(A[1], A[2], A[3], C[1])\fP بسط می‌یابد\&. اگر عبارت _تنها_ از توابع تجمیعی تشکیل شده باشد، صرف‌نظر از تعداد باندهای ورودی، یک باند خروجی تکی تولید خواهد شد. با این حال، اگر عبارت حاوی یک ارجاع غیرتجمیعی به تمام باندهای یک ورودی باشد، آن‌گاه همچنان به ازای هر باند ورودی، یک باند خروجی تولید خواهد شد. یک نمونه ساده، عبارت \fBA / sum(A)\fP است که یک رستر N\-بانده تولید می‌کند که در آن هر باند خروجی، سهم باند ورودی از مجموع کل را شامل می‌شود. .sp می‌توان چندین محاسبه را مشخص کرد؛ باند(های) خروجی به ازای هر عبارت و به ترتیبی که ارائه شده‌اند، تولید خواهند شد. .sp رسترهای ورودی پیش از انجام محاسبات به اعداد ممیز شناور ۶۴ بیتی تبدیل خواهند شد. .sp از GDAL 3.12 به بعد، همچنین می‌توان با تعیین \fI\%\-\-dialect\fP بر روی \fBbuiltin\fP\&، از یک \fI\%تابع پیکسلی C++ در VRT\fP (مانند \fBsum\fP، \fBmean\fP، \fBmin\fP، \fBmax\fP) استفاده کرد. آرگومان‌های توابع در داخل پرانتز ارسال می‌شوند، مانند \fBsum(k=1)\fP، \fBmin(propagateNoData=true)\fP یا \fBinterpolate_linear(t0=1,dt=1,t=10)\fP\&..SS "متغیرهای توکار (Built\-in variables)" .sp متغیرهای توکار زیر در عبارت‌ها در دسترس هستند: .INDENT 7.0 .IP \(bu 2 \fB_CENTER_X_\fP: مختصات X مرکز پیکسل، بیان‌شده در CRS مجموعه‌داده .IP \(bu 2 \fB_CENTER_Y_\fP: مختصات Y مرکز پیکسل، بیان‌شده در CRS مجموعه‌داده .IP \(bu 2 \fBNODATA\fP: مقدار خروجی \fINoData\fP، در صورت وجود. .UNINDENT .sp این متغیرها برای محاسباتی که به موقعیت مکانی وابسته هستند مفیدند، مانند تصحیحات مبتنی بر عرض جغرافیایی، تقریب زاویه تابش خورشید، یا ماسک‌های منطقه‌ای. .sp برای مشاهده یک نمونه کاربرد، \fI\%Example 7\fP را ببینید. .sp نکته: برای کار با مقادیر طول/عرض جغرافیایی، مجموعه‌داده ورودی باید در یک سامانه مرجع مختصات جغرافیایی (برای نمونه EPSG:4326) باشد. .UNINDENT .INDENT 0.0 .TP .B \-\-dialect muparser|builtin در نسخه 3.12 اضافه شد. .sp موتور عبارتی را که برای تفسیر مقدار \fI\%\-\-calc\fP استفاده می‌شود مشخص می‌کند. پیش‌فرض \fBmuparser\fP است. .UNINDENT .INDENT 0.0 .TP .B \-\-flatten در نسخه 3.12 اضافه شد. .sp تولید یک رستر خروجی تک‌باند به ازای هر عبارت، حتی اگر مجموعه‌داده‌های ورودی چندبانده باشند. .sp برای گویش پیش‌فرض muparser، استفاده از نام یک رستر ورودی (برای نمونه A) معادل با \fBA[1],A[2],...,A[n]\fP است. چنین ساختاری با توابع \fBmin\fP، \fBmax\fP، \fBsum\fP و \fBavg\fP در muparser کار می‌کند. .sp برای نمونه، اگر دو رستر A و B را با ۳ باند برای هر کدام در نظر بگیریم، آنگاه \fB\-\-flatten \-\-calc \(dqavg(A)\-avg(B)\(dq\fP معادل خواهد بود با \fB\-\-calc \(dqavg(A[1],A[2],A[3])\-avg(B[1],B[2],B[3])\(dq\fP .sp و دستور \fB\-\-flatten \-\-dialect=builtin \-\-calc mean\fP یک تک‌باند را با میانگین تمام ۴ باند ورودی محاسبه خواهد کرد. .UNINDENT .INDENT 0.0 .TP .B \-i [=] یک مجموعه‌داده ورودی را برای پردازش انتخاب می‌کند. اگر بیش از یک مجموعه‌داده ورودی مشخص شود، پیش از هر مجموعه‌داده باید نامی قرار گیرد که در \fI\%\-\-calc\fP به آن ارجاع داده خواهد شد. .UNINDENT .INDENT 0.0 .TP .B \-\-no\-check\-extent بررسی نمی‌کند که رسترهای ورودی وسعت مکانی یکسانی دارند یا خیر. در عوض لازم است رسترهای ورودی ابعاد یکسانی داشته باشند. زمین‌مرجع (geotransform) اولین ورودی به خروجی اختصاص داده خواهد شد. .UNINDENT .INDENT 0.0 .TP .B \-\-no\-check\-crs سامانه‌های مرجع مکانی ورودی‌ها را از نظر سازگاری بررسی نمی‌کند. فرض خواهد شد که همه ورودی‌ها دارای سامانه مرجع مکانی ورودی اول هستند و همین سامانه مرجع مکانی برای خروجی استفاده خواهد شد. .UNINDENT .INDENT 0.0 .TP .B \-\-nodata در نسخه 3.12 اضافه شد. .sp مقدار NoData را برای مجموعه‌داده خروجی تنظیم می‌کند. می‌تواند برابر \(dqnone\(dq قرار گیرد تا مقدار NoData تعریف‌نشده باقی بماند. اگر \fI\%\-\-nodata\fP مشخص نشود، \fBgdal raster calc\fP از مقدار NoData اولین مجموعه‌داده مبدأ که دارای آن باشد استفاده خواهد کرد. .UNINDENT .INDENT 0.0 .TP .B \-\-propagate\-nodata در نسخه 3.12 اضافه شد. .sp در صورت تنظیم، وجود مقدار NoData در هر مجموعه‌داده ورودیِ استفاده‌شده در عبارت، باعث می‌شود که مقدار خروجی NoData گردد. .UNINDENT .SH "گزینه‌های استاندارد (STANDARD OPTIONS)" .INDENT 0.0 .TP .B \-\-append رستر ورودی را به عنوان یک زیرمجموعه‌داده (subdataset) جدید به یک فایل خروجیِ موجود اضافه (الحاق) می‌کند. تنها با درایورهایی کار می‌کند که از افزودن زیرمجموعه‌داده‌ها پشتیبانی می‌کنند، مانند \fI\%GTiff \-\- GeoTIFF File Format\fP و \fI\%GPKG \-\- GeoPackage raster\fP\&. این گزینه همچنین مجموعه‌داده خروجی را در صورتی که از قبل وجود نداشته باشد ایجاد می‌کند. .UNINDENT .INDENT 0.0 .TP .B \-\-co, \-\-creation\-option = بسیاری از قالب‌ها یک یا چند گزینه ساخت (creation option) اختیاری دارند که می‌توان از آن‌ها برای کنترل جزئیات فایل ایجادشده استفاده کرد. برای نمونه، درایور GeoTIFF از گزینه‌های ساختی برای کنترل فشرده‌سازی و این‌که آیا فایل باید کاشی‌بندی‌شده (tiled) باشد پشتیبانی می‌کند. .sp می‌تواند تکرار شود. .sp گزینه‌های ساخت موجود بسته به درایور قالب متغیر هستند، و برخی قالب‌های ساده اصلاً هیچ گزینه ساختی ندارند. فهرستی از گزینه‌های پشتیبانی‌شده برای یک قالب را می‌توان با گزینه خط فرمان \fI\%\-\-formats\fP مشاهده کرد، اما مستندات مربوط به قالب، منبع قطعی اطلاعات درباره گزینه‌های ساخت درایور است. برای گزینه‌های ساخت مجاز هر قالب، مستندات اختصاصی قالب در \fI\%Raster drivers\fP را ببینید. .UNINDENT .INDENT 0.0 .TP .B \-\-if, \-\-input\-format نام قالب/درایوری که برای باز کردن فایل(های) ورودی امتحان می‌شود. معمولاً نیازی به مشخص کردن آن نیست، اما در مواردی که تشخیص خودکار درایور در انتخاب درایور مناسب ناموفق باشد، می‌تواند برای صرف‌نظر از تشخیص خودکار استفاده شود. این گزینه می‌تواند چندین بار برای تعیین چندین درایور نامزد تکرار شود. توجه داشته باشید که این کار درایورها را مجبور به باز کردن مجموعه‌داده نمی‌کند. به ویژه، برخی درایورها الزاماتی روی پسوند فایل دارند. .sp می‌تواند تکرار شود. .UNINDENT .INDENT 0.0 .TP .B \-\-oo, \-\-open\-option = گزینه باز کردن مجموعه‌داده (مخصوص قالب). .sp می‌تواند تکرار شود. .UNINDENT .INDENT 0.0 .TP .B \-f, \-\-of, \-\-format, \-\-output\-format قالب رستر خروجی برای استفاده را مشخص می‌کند. مقادیر مجاز را می‌توان با این دستور به دست آورد: \fBgdal \-\-formats | grep raster | grep rw | sort\fP .UNINDENT .INDENT 0.0 .TP .B \-\-ot, \-\-datatype, \-\-output\-data\-type نوع داده خروجی از میان \fBByte\fP، \fBInt8\fP، \fBUInt16\fP، \fBInt16\fP، \fBUInt32\fP، \fBInt32\fP، \fBUInt64\fP، \fBInt64\fP، \fBCInt16\fP، \fBCInt32\fP، \fBFloat32\fP، \fBFloat64\fP، \fBCFloat32\fP، \fBCFloat64\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-overwrite به برنامه اجازه می‌دهد فایل یا مجموعه‌داده هدفِ موجود را بازنویسی (overwrite) کند. در غیر این صورت، به طور پیش‌فرض اگر فایل یا مجموعه‌داده هدف از قبل وجود داشته باشد، \fBgdal\fP با خطا متوقف می‌شود. .UNINDENT.SH "وضعیت خروج (EXIT STATUS)" .sp برنامه در صورت موفقیت کد وضعیت 0 و در صورت بروز خطا کدی غیر از صفر را برمی‌گرداند (خطاهای غیرمسدودکننده که به‌صورت هشدار صادر می‌شوند، اجرای موفقیت‌آمیز در نظر گرفته می‌شوند). .SH "مثال‌ها (EXAMPLES)" .SS مثال ۱: مجموع سه‌ فایل به‌ازای هر باند .INDENT 0.0 .INDENT 3.5 .sp .EX gdal raster calc \-i \(dqA=file1.tif\(dq \-i \(dqB=file2.tif\(dq \-i \(dqC=file3.tif\(dq \-\-calc \(dqA+B+C\(dq \-o out.tif .EE .UNINDENT .UNINDENT .SS مثال ۲: میانگین تمام باندهای هر مجموعه داده به‌ازای هر مجموعه داده .INDENT 0.0 .INDENT 3.5 .sp .EX gdal raster calc \-i \(dqA=file1.tif\(dq \-i \(dqB=file2.tif\(dq \-i \(dqC=file3.tif\(dq \-\-flatten \-\-calc \(dqavg(A)\(dq \-\-calc \(dqavg(B)\(dq \-\-calc \(dqavg(C)\(dq \-o out.tif .EE .UNINDENT .UNINDENT .SS مثال ۳: بیشینه سه‌ فایل به‌ازای هر باند .INDENT 0.0 .INDENT 3.5 .sp .EX gdal raster calc \-i \(dqA=file1.tif\(dq \-i \(dqB=file2.tif\(dq \-i \(dqC=file3.tif\(dq \-\-calc \(dqmax(A,B,C)\(dq \-o out.tif .EE .UNINDENT .UNINDENT .SS مثال ۴: تنظیم مقادیر صفر و کمتر از آن روی NaN .INDENT 0.0 .INDENT 3.5 .sp .EX gdal raster calc \-i \(dqA=input.tif\(dq \-o result.tif \-\-calc=\(dqA > 0 ? A : NaN\(dq .EE .UNINDENT .UNINDENT .SS مثال ۵: محاسبه میانگین (به‌صورت یک تک‌باند) تمام باندهای دو مجموعه داده ورودی .INDENT 0.0 .INDENT 3.5 .sp .EX gdal raster calc \-i A=input1.tif \-i B=input2.tif \-o result.tif \-\-flatten \-\-calc=mean \-\-dialect=builtin .EE .UNINDENT .UNINDENT .SS مثال ۶: تولید یک لایه جهت شیب (aspect) ماسک‌شده در زاویه شیب بیش از ۲ درجه، با استفاده از خط‌لوله‌های تو‌در‌تو (از GDAL 3.12.1 به بعد) .INDENT 0.0 .INDENT 3.5 .sp .EX gdal raster calc \-i \(dqSLOPE=[ read dem.tif ! slope ]\(dq \-i \(dqASPECT=[ read dem.tif ! aspect ]\(dq \-o result.tif \-\-calc \(dq(SLOPE >= 2) ? ASPECT : \-9999\(dq \-\-nodata \-9999 .EE .UNINDENT .UNINDENT .SS مثال ۷: محاسبه مبتنی بر عرض جغرافیایی با استفاده از _CENTER_Y_ .INDENT 0.0 .INDENT 3.5 .sp .EX gdal raster calc \-i A=input.tif \e \-\-calc=\(dqsin(_CENTER_Y_ * 0.0174533)\(dq \e \-o output.tif .EE .UNINDENT .UNINDENT .SH "نویسندگان (AUTHORS)" Dan Baston .SH "کپی‌رایت و تکثیر (COPYRIGHT)" 1998-2026 .\" Generated by docutils manpage writer. .