GDAL-RASTER-HILLSHADE(1)

GDAL

GDAL-RASTER-HILLSHADE(1)

نام (NAME)

gdal-raster-hillshade - تولید نقشه برجسته‌نما (سایه‌روشن)

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

خلاصه دستور (SYNOPSIS)

کاربرد: gdal raster hillshade [OPTIONS] <INPUT> <OUTPUT>
تولید یک نقشه برجسته‌نما (سایه‌روشن)
آرگومان‌های موقعیتی:
  -i, --input <INPUT>                                  مجموعه‌داده‌های رستر ورودی [الزامی] [در خط‌لوله‌ها در دسترس نیست]
  -o, --output <OUTPUT>                                مجموعه‌داده رستر خروجی [الزامی] [در خط‌لوله‌ها در دسترس نیست]
گزینه‌های عمومی:
  -h, --help                                           نمایش پیام راهنما و خروج
  --json-usage                                         نمایش نحوه استفاده در قالب یک سند JSON و خروج
  --config <KEY>=<VALUE>                               گزینه پیکربندی [می‌تواند تکرار شود]
  -q, --quiet                                          حالت بی‌صدا (بدون نوار پیشرفت یا پیام هشدار) [در خط‌لوله‌ها در دسترس نیست]
گزینه‌ها:
  -f, --of, --format, --output-format <OUTPUT-FORMAT>  قالب خروجی (مقدار "GDALG" مجاز است) [در خط‌لوله‌ها در دسترس نیست]
  --co, --creation-option <KEY>=<VALUE>                گزینه ساخت [می‌تواند تکرار شود] [در خط‌لوله‌ها در دسترس نیست]
  --overwrite                                          آیا رونویسی مجموعه‌داده خروجی موجود مجاز است [در خط‌لوله‌ها در دسترس نیست]
                                                       ناسازگار با --append
  --append                                             الحاق به عنوان یک زیرمجموعه‌داده به خروجی موجود [در خط‌لوله‌ها در دسترس نیست]
                                                       ناسازگار با --overwrite
  -b, --band <BAND>                                    باند ورودی (شاخص مبتنی بر ۱) (پیش‌فرض: 1)
  -z, --zfactor <ZFACTOR>                              بزرگ‌نمایی عمودی برای پیش‌ضرب در مقادیر ارتفاع
  --xscale <XSCALE>                                    نسبت واحدهای عمودی به واحدهای افقی محور X
  --yscale <YSCALE>                                    نسبت واحدهای عمودی به واحدهای افقی محور Y
  --azimuth <AZIMUTH>                                  زاویه سمت (آزیموت) نور به درجه (پیش‌فرض: 315)
  --altitude <ALTITUDE>                                زاویه ارتفاع نور به درجه (پیش‌فرض: 45)
  --gradient-alg <GRADIENT-ALG>                        الگوریتم مورد استفاده برای محاسبه گرادیان زمین. GRADIENT-ALG=Horn|ZevenbergenThorne (پیش‌فرض: Horn)
  --variant <VARIANT>                                  گونه الگوریتم سایه‌روشن. VARIANT=regular|combined|multidirectional|Igor (پیش‌فرض: regular)
  --no-edges                                           عدم تلاش برای درون‌یابی مقادیر در لبه‌های مجموعه‌داده یا نزدیک به مقادیر nodata
گزینه‌های پیشرفته:
  --if, --input-format <INPUT-FORMAT>                  قالب‌های ورودی [می‌تواند تکرار شود] [در خط‌لوله‌ها در دسترس نیست]
  --oo, --open-option <KEY>=<VALUE>                    گزینه‌های باز کردن [می‌تواند تکرار شود] [در خط‌لوله‌ها در دسترس نیست]

توضیحات (DESCRIPTION)

دستور gdal raster hillshade از هر رستر ارتفاعی پشتیبانی‌شده توسط GDAL، یک نقشه برجسته‌نما (سایه‌روشن) تولید می‌کند.

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

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

مقدار 0 به عنوان مقدار nodata خروجی استفاده می‌شود. اگر حداقل یک پیکسل با مقدار nodata در پنجره 3x3 متمرکز بر هر پیکسل مبدأ یافت شود، یک مقدار nodata در مجموعه‌داده مقصد صادر خواهد شد. به طور پیش‌فرض، الگوریتم با درون‌یابی مقادیر ناموجود، مقادیر را در لبه‌های تصویر یا در صورت یافت شدن یک مقدار nodata در پنجره 3x3 محاسبه می‌کند، مگر اینکه --no-edges مشخص شده باشد؛ در این حالت یک حاشیه به ضخامت ۱ پیکسل در اطراف تصویر با مقدار nodata تنظیم خواهد شد.

به طور کلی، فرض بر این است که واحدهای x، y و z یکسان هستند. با این حال، اگر هیچ‌کدام از --xscale و --yscale مشخص نشده باشند، و سامانه مرجع مختصات (CRS) یک CRS جغرافیایی یا تصویرشده باشد، به طور خودکار نسبت مناسب را بر اساس واحدهای CRS و همچنین مقدار احتمالی واحدهای باند رستر (آن‌طور که توسط GDALRasterBand::GetUnitType() برگردانده می‌شود، در صورتی که metre،‏ foot international یا US survey foot باشد) تعیین می‌کند. توجه داشته باشید که برای CRS جغرافیایی، نتیجه برای مجموعه‌داده‌های مبدأ در عرض‌های جغرافیایی بالا ممکن است نادرست باشد، و ممکن است بازتصویرسازی پیشین به یک تصویر قطبی با استفاده از gdal raster reproject مورد نیاز باشد.

اگر واحدهای x (شرقی-غربی) و y (شمالی-جنوبی) یکسان باشند، اما واحدهای z (ارتفاع) متفاوت باشند، می‌توان از --xscale و --yscale برای تنظیم نسبت واحدهای عمودی به افقی استفاده کرد. برای CRS جغرافیایی نزدیک به خط استوا، جایی که واحدهای عرض جغرافیایی و طول جغرافیایی مشابه هستند، واحدهای ارتفاع (z) را می‌توان با استفاده از scale=370400 (اگر ارتفاع بر حسب فوت باشد) یا scale=111120 (اگر ارتفاع بر حسب متر باشد) برای سازگار شدن تبدیل کرد. برای مکان‌هایی که نزدیک به خط استوا نیستند، مقدار --xscale را می‌توان برابر با مقدار --yscale ضرب در کسینوس میانگین عرض جغرافیایی رستر در نظر گرفت..SH "خروجی GDALG (مجموعه‌داده در لحظه / جریانی) (GDALG OUTPUT (ON-THE-FLY / STREAMED DATASET))"

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

گزینه‌های ویژه‌ی برنامه (PROGRAM-SPECIFIC OPTIONS)

--altitude <ALTITUDE>: ارتفاع زاویه‌ای تابش نور بر حسب درجه. مقدار ۹۰ برای نوری که مستقیم از بالای DEM می‌تابد، و ۰ در صورت تابش مایل افقی. مقدار پیش‌فرض ۴۵ درجه است.
این گزینه با --variant=Igor مانعة‌الجمع است و نمی‌توانند هم‌زمان استفاده شوند.

--azimuth <AZIMUTH>: سمت (آزیموت) تابش نور بر حسب درجه. مقدار ۰ برای تابش از بالای رَستر، ۹۰ از شرق، و... مقدار پیش‌فرض ۳۱۵ است که به‌ندرت نیاز به تغییر دارد، زیرا مقداری است که معمولاً برای تولید نقشه‌های سایه‌روشن به‌کار می‌رود.
این گزینه با --variant=multidirectional مانعة‌الجمع است.

-b, --band <BAND>: اندیس باندی (شروع از ۱) که سایه‌روشن (hillshade) باید برای آن محاسبه شود.

--gradient-alg Horn|ZevenbergenThorne: الگوریتم مورد استفاده برای محاسبه گرادیان ناهمواری. مقدار پیش‌فرض Horn است. مطالعات نشان می‌دهند که فرمول Zevenbergen & Thorne برای چشم‌اندازهای هموارتر مناسب‌تر است، در حالی که فرمول Horn' عملکرد بهتری روی ناهمواری‌های خشن‌تر دارد.

--no-edges: برای درون‌یابی مقادیر در لبه‌های مجموعه‌داده یا در نزدیکی مقادیر nodata تلاشی نکن.

--variant regular|combined|multidirectional|Igor: گونه‌ی الگوریتم سایه‌روشن (hillshade):

•: regular: مقادیر سایه‌روشن، شیب محاسبه‌شده را با سمت و ارتفاع زاویه‌ای تابش بر اساس فرمول زیر ترکیب می‌کند:

{Hillshade} = 1 + 254.0 * ((\sin(altitude) * cos(slope)) + (cos(altitude) * sin(slope) * cos(azimuth - \frac{\pi}{2} - aspect)))

combined: سایه‌زنی ترکیبی؛ ترکیبی از شیب و سایه‌زنی مایل.
multidirectional: سایه‌زنی چندجهته؛ ترکیبی از سایه‌روشن ناشی از تابش از سمت‌های ۲۲۵ درجه، ۲۷۰ درجه، ۳۱۵ درجه و ۳۶۰ درجه. فرمول این مرجع را اعمال می‌کند: http://pubs.usgs.gov/of/1992/of92-422/of92-422.pdf
Igor: سایه‌زنی که تلاش می‌کند اثرات منفی روی سایر عوارض نقشه در لایه‌های زیرین را به حداقل برساند. سایه‌روشن Igor' از فرمول Maperitive استفاده می‌کند: http://maperitive.net/docs/Commands/GenerateReliefImageIgor.html

--xscale <scale>

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

نسبت واحدهای عمودی به واحدهای افقی محور X. اگر واحد افقی DEM مبدأ درجه باشد (مانند سیستم تصویر Lat/Long WGS84)، در صورتی که واحدهای عمودی متر باشند می‌توانید از scale=111120 استفاده کنید (یا اگر بر حسب فوت باشند از scale=370400).

اگر هیچ‌یک از گزینه‌های --xscale و --yscale مشخص نشده باشند و CRS یک CRS جغرافیایی یا تصویرشده باشد، دستور gdal raster hillshade به‌طور خودکار نسبت مناسب را بر اساس واحدهای CRS و همچنین مقدار احتمالی واحدهای باند رَستر (که توسط GDALRasterBand::GetUnitType() بازگردانده می‌شود، در صورتی که متر، فوت بین‌المللی یا فوت نقشه‌برداری ایالات متحده باشد) تعیین می‌کند. توجه داشته باشید که برای CRS جغرافیایی، نتیجه برای مجموعه‌داده‌های مبدأ در عرض‌های جغرافیایی بالا ممکن است نادرست باشد و ممکن است بازتصویرسازی پیشین به یک سیستم تصویر قطبی لازم باشد.

اگر --xscale مشخص شود، --yscale نیز باید مشخص گردد.

--yscale <scale>

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

نسبت واحدهای عمودی به واحدهای افقی محور Y. اگر واحد افقی DEM مبدأ درجه باشد (مانند سیستم تصویر Lat/Long WGS84)، در صورتی که واحدهای عمودی متر باشند می‌توانید از scale=111120 استفاده کنید (یا اگر بر حسب فوت باشند از scale=370400).

اگر --yscale مشخص شود، --xscale نیز باید مشخص گردد.

-z, --zfactor <ZFACTOR>: ضریب بزرگ‌نمایی عمودی که برای پیش‌ضرب در مقادیر ارتفاعی استفاده می‌شود.

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

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

بسیاری از فرمت‌ها یک یا چند گزینه اختیاری ساخت دارند که می‌توان از آن‌ها برای کنترل جزئیات فایل ایجادشده استفاده کرد. برای نمونه، درایور 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

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

وضعیت خروج (RETURN STATUS CODE)

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

مثال‌ها (EXAMPLES)

مثال ۱: تولید نقشه برجسته‌نمایی سایه‌روشن از یک فایل DTED0 با استفاده از ضریب اغراق عمودی 30.

$ gdal raster hillshade --zfactor=30 n43.dt0 out.tif --overwrite

مثال ۲: ترکیب خروجی نقشه برجسته‌نمایی سایه‌روشن و رندرینگ هایپسومتریک بر روی یک DEM برای ایجاد نقشه برجسته‌نمایی سایه‌روشن رنگی.

$ gdal pipeline read n43.tif ! \
                color-map --color-map color_file.txt ! \
                blend --operator=hsv-value --overlay \
                    [ read n43.tif ! hillshade -z 30 ] ! \
                write out.tif --overwrite

Even Rouault <even.rouault@spatialys.com>

کپی‌رایت و تکثیر (COPYRIGHT)

1998-2026

August 18, 2026