GDAL-RASTER-COLOR-MAP(1) GDAL GDAL-RASTER-COLOR-MAP(1)

gdal-raster-color-map - تولید یک مجموعه داده RGB یا RGBA از یک تک‌باند با استفاده از نقشه‌ی رنگ

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

Usage: gdal raster color-map [OPTIONS] <INPUT> <OUTPUT>
Generate a RGB or RGBA dataset from a single band, using a color map
Positional arguments:
  -i, --input <INPUT>                                  Input raster datasets [required] [not available in pipelines]
  -o, --output <OUTPUT>                                Output raster 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]
  --overwrite                                          Whether overwriting existing output dataset is allowed [not available in pipelines]
                                                       Mutually exclusive with --append
  --append                                             Append as a subdataset to existing output [not available in pipelines]
                                                       Mutually exclusive with --overwrite
  -b, --band <BAND>                                    Input band (1-based index) (default: 1)
  --color-map <COLOR-MAP>                              Color map filename
  --add-alpha                                          Adds an alpha mask band to the destination.
  --color-selection <COLOR-SELECTION>                  How to compute output colors from input values. COLOR-SELECTION=interpolate|exact|nearest (default: interpolate)
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]

دستور gdal raster color-map با استفاده از یک نقشه‌ی رنگ (color map)—که یا مستقیماً به باند رستر متصل است یا از یک فایل متنی خارجی خوانده می‌شود—یک مجموعه داده RGB یا RGBA از یک باند منفرد تولید می‌کند. این ابزار معمولاً برای ایجاد نقشه‌های ارتفاع‌سنجی (hypsometric) از یک مدل رقومی ارتفاع (DEM) استفاده می‌شود.

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

این برنامه از سریال‌سازی خط فرمان به عنوان یک فایل JSON با استفاده از قالب خروجی GDALG پشتیبانی می‌کند. فایل حاصل را می‌توان سپس با استفاده از درایور GDALG: GDAL Streamed Algorithm به عنوان یک مجموعه داده رستری باز کرد و خط لوله‌ی (pipeline) مشخص‌شده را به صورت بلادرنگ (on-the-fly) یا جریانی اعمال نمود.

یک باند ماسک آلفا (alpha mask) به خروجی اضافه می‌کند.
اندیس باندی که باید پردازش شود (شروع از ۱).
نام فایل نقشه‌ی رنگ حاوی تناظر بین مقادیر گوناگون رستر و رنگ مورد نظر مربوطه.

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

فایل پیکربندی رنگ متنی به طور کلی شامل ۴ ستون در هر خط است: مقدار رستر و مؤلفه‌های متناظر قرمز (Red)، سبز (Green) و آبی (Blue) (بین ۰ تا ۲۵۵). مقدار رستر می‌تواند هر مقدار ممیز شناور یا کلمه‌ی کلیدی nv برای مقدار nodata باشد. رستر را می‌توان به صورت درصد نیز بیان کرد: 0% کمترین مقدار موجود در رستر و 100% بیشترین مقدار آن خواهد بود.

می‌توان یک ستون اضافی اختیاری نیز برای مؤلفه‌ی آلفا اضافه کرد. اگر مشخص نشود، کدر بودن کامل (۲۵۵) در نظر گرفته می‌شود.

جداکننده‌های مختلف فیلد پذیرفته می‌شوند: ویرگول، تب، فاصله‌ها و ':'.

رنگ‌های رایج مورد استفاده در GRASS را نیز می‌توان با نام آن‌ها به جای سه‌گانه‌ی RGB مشخص کرد. فهرست پشتیبانی‌شده عبارت است از: white، black، red، green، blue، yellow، magenta، cyan، aqua، grey/gray، orange، brown، purple/violet و indigo.

فایل‌های پالت GMT با پسوند .cpt نیز پشتیبانی می‌شوند (تنها با COLOR_MODEL = RGB).

نکته: نحو فایل پیکربندی رنگ از ساختار پشتیبانی‌شده در ابزار r.colors در GRASS گرفته شده است. فایل‌های جدول رنگ ESRI HDR با پسوند (.clr) نیز با این نحو مطابقت دارند. مؤلفه‌ی آلفا و پشتیبانی از تب و ویرگول به عنوان جداکننده، افزونه‌های مختص GDAL هستند.

برای مثال:

3500   white
2500   235:220:175
50%   190 185 135
700    240 250 150
0      50  180  50
nv     0   0   0   0

برای پیاده‌سازی حالت «گرد کردن به پایین» ("round to the floor value")، مقدار رستر می‌تواند با یک مقدار جدید که کمی بالاتر از آستانه است تکرار شود. برای مثال برای داشتن رنگ قرمز در [0,10]، سبز در ]10,20] و آبی در ]20,30]:

0       red
10      red
10.001  green
20      green
20.001  blue
30      blue
نحوه‌ی محاسبه‌ی رنگ‌های خروجی بر اساس مقادیر ورودی:
  • interpolate (پیش‌فرض): هنگامی که مقدار رستر بین دو مدخل از نقشه‌ی رنگ قرار می‌گیرد، درون‌یابی خطی اعمال می‌شود.
  • exact: تنها مقادیر رستر ورودی که دقیقاً منطبق با یک مدخل نقشه‌ی رنگ باشند رنگ‌آمیزی می‌شوند. اگر هیچ مدخل رنگی منطبقی یافت نشود، چهارگانه‌ی RGBA به صورت "0,0,0,0" استفاده خواهد شد.
  • nearest: به مقادیر رستر ورودی، نزدیک‌ترین مدخل نقشه‌ی رنگ اختصاص می‌یابد.

نکته:

این گزینه تنها زمانی اعمال می‌شود که --color-map مشخص شده باشد.

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

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

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

قالب رستر خروجی مورد استفاده. مقادیر مجاز را می‌توان از طریق دستور زیر به دست آورد: gdal --formats | grep raster | grep rw | sort
به برنامه اجازه‌ی بازنویسی روی فایل یا مجموعه داده مقصد فعلی را می‌دهد. در غیر این صورت، به صورت پیش‌فرض، اگر فایل یا مجموعه داده مقصد از قبل وجود داشته باشد، gdal با خطا مواجه می‌شود.

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

$ gdal raster color-map --color-map=color-map.txt n43.dt0 out.tif --overwrite

Even Rouault <even.rouault@spatialys.com>

1998-2026

August 18, 2026