--help

نمایش این پیام راهنما و خروج.

--help-general

نمایش یک پیام کاربردی کوتاه برای گزینه‌های عمومی خط فرمان GDAL و خروج.

-q, --quiet

فرونشاندن پیام‌های پیشرفت و سایر خروجی‌های غیرخطا.

-ot <type>

اجبار باندهای تصویر خروجی به داشتن یک نوع داده مشخص که توسط درایور پشتیبانی می‌شود؛ می‌تواند یکی از موارد زیر باشد: Byte، Int8، UInt16، Int16، UInt32، Int32، UInt64، Int64، Float32، Float64، CInt16، CInt32، CFloat32 یا CFloat64.

-strict

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

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

-if <format>

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

اضافه‌شده در نسخه 3.2.

-of <format>

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

-b <band>

انتخاب باند ورودی band برای خروجی. شماره‌گذاری باندها از ۱ است. می‌توان از چندین سوئیچ -b برای انتخاب مجموعه‌ای از باندهای ورودی جهت نوشتن در فایل خروجی، یا برای مرتب‌سازی مجدد باندها استفاده کرد. band همچنین می‌تواند روی "mask,1" (یا فقط "mask") تنظیم شود تا به معنی باند ماسکِ نخستین باند از مجموعه داده ورودی باشد.

-mask <band>

انتخاب یک باند ورودی band برای ایجاد باند ماسک مجموعه داده خروجی. شماره‌گذاری باندها از ۱ است. band می‌تواند روی "none" تنظیم شود تا از کپی کردن ماسک سراسری مجموعه داده ورودی در صورت وجود جلوگیری کند. در غیر این صورت به‌طور پیش‌فرض کپی می‌شود ("auto")، مگر اینکه ماسک یک کانال آلفا باشد، یا صراحتاً برای یک باند معمولی مجموعه داده خروجی استفاده شود ("-b mask";). همچنین band می‌تواند روی "mask,1" (یا فقط "mask") تنظیم شود تا به معنی باند ماسکِ باند اول مجموعه داده ورودی باشد.

-expand gray|rgb|rgba

برای بازنمود یک مجموعه داده با ۱ باند دارای جدول رنگ به صورت یک مجموعه داده با ۳ باند (RGB) یا ۴ باند (RGBA). برای درایورهای خروجی مانند JPEG، JPEG2000، MrSID، ECW که از مجموعه‌داده‌های دارای شاخص رنگ پشتیبانی نمی‌کنند مفید است. مقدار 'gray' امکان بسط یک مجموعه داده دارای جدول رنگ را که تنها حاوی سطوح خاکستری است به یک مجموعه داده با شاخص خاکستری فراهم می‌کند.

-outsize <xsize>[%]|0 <ysize>[%]|0

تنظیم اندازه فایل خروجی. اندازه خروجی بر حسب پیکسل و سطر است، مگر اینکه '%' اضافه شده باشد که در این صورت به عنوان کسری از اندازه تصویر ورودی خواهد بود. اگر یکی از این ۲ مقدار روی 0 تنظیم شود، مقدار آن از روی مقدار دیگر و با حفظ نسبت ابعاد مجموعه داده منبع تعیین خواهد شد.

-ovr {<level>|AUTO|AUTO-<n>|NONE}

در نگارش 3.6 اضافه شد.

برای تعیین اینکه کدام سطح نمای کلی (overview) فایل منبع باید استفاده شود. انتخاب پیش‌فرض، AUTO، سطحی از نمای کلی را انتخاب می‌کند که تفکیک‌پذیری آن به تفکیک‌پذیری هدف نزدیک‌تر باشد. برای انتخاب سطحی خاص، یک مقدار عدد صحیح (مبتنی بر صفر، یعنی 0=نخستین سطح نمای کلی) مشخص کنید. عبارت AUTO-n را که در آن n یک عدد صحیح بزرگ‌تر یا مساوی با 1 است مشخص کنید تا سطح نمای کلی زیر AUTO انتخاب شود. یا NONE را مشخص کنید تا استفاده از تفکیک‌پذیری پایه اجبار شود (می‌تواند زمانی مفید باشد که نماهای کلی با یک روش بازنمونه‌برداری کم‌کیفیت ایجاد شده باشند، و یک روش بازنمونه‌برداری باکیفیت‌تر توسط -r تعیین شده باشد.)

هنگامی که -ovr به صورت یک مقدار عدد صحیح مشخص شده باشد و هیچ‌کدام از -outsize یا -tr تعیین نشده باشند، اندازه نمای کلی به عنوان اندازه خروجی استفاده خواهد شد.

هنگامی که -ovr مشخص شده باشد، مقادیر -srcwin باید به صورت آفست پیکسلی و اندازه مجموعه‌داده منبع با تفکیک‌پذیری کامل بیان شوند. به همین ترتیب، هنگام استفاده از -outsize با مقادیر درصدی، آن‌ها به اندازه مجموعه‌داده منبع با تفکیک‌پذیری کامل اشاره دارند.

-r {nearest|bilinear|cubic|cubicspline|lanczos|average|rms|mode}

انتخاب الگوریتم بازنمونه‌برداری (resampling).

nearest (پیش‌فرض) یک بازنمونه‌بردار نزدیک‌ترین همسایه (نمونه‌برداری ساده) را اعمال می‌کند.

average میانگین تمام پیکسل‌های مشارکت‌کننده غیر NODATA را محاسبه می‌کند. از GDAL 3.1 به بعد، این یک میانگین وزنی است که وزن پیکسل‌های منبعی را که به طور کامل در پیکسل هدف مشارکت ندارند، به درستی لحاظ می‌کند.

rms ریشه میانگین مربعات / میانگین مربعی تمام پیکسل‌های مشارکت‌کننده غیر NODATA را محاسبه می‌کند (GDAL >= 3.3).

bilinear یک هسته پیچش درون‌یابی دوخطی (bilinear) را اعمال می‌کند.

cubic یک هسته پیچش مکعبی (cubic) را اعمال می‌کند.

cubicspline یک هسته پیچش B-Spline اعمال می‌کند.

lanczos یک هسته پیچش سینک پنجره‌دار لانچوس (Lanczos windowed sinc) را اعمال می‌کند.

mode مقداری را انتخاب می‌کند که بیشترین تکرار را در بین تمام نقاط نمونه‌برداری‌شده دارد.

-scale [<src_min> <src_max> [<dst_min> <dst_max>]]

تغییر مقیاس مقادیر پیکسل‌های ورودی از بازه src_min تا src_max به بازه dst_min تا dst_max. در صورت حذف شدن، بازه خروجی از کمترین مقدار تا بیشترین مقدار مجاز برای انواع داده عدد صحیح (به عنوان مثال از 0 تا 255 برای خروجی Byte) یا از 0 تا 1 برای انواع داده ممیز شناور خواهد بود. در صورت حذف شدن، بازه ورودی به طور خودکار از کل مجموعه‌داده منبع محاسبه می‌شود (نه فقط پنجره مورد نظر که احتمالاً توسط -srcwin یا -projwin مشخص شده است). این ممکن است در مجموعه‌داده‌های منبع بزرگ عملیاتی کند باشد، و در صورت استفاده چندباره از آن برای فراخوانی‌های متعدد gdal_translate، ممکن است فراخوانی پیشین gdalinfo -stats {source_dataset} برای پیش‌محاسبه آمار، برای فرمت‌هایی که از ذخیره‌سازی محاسبات آماری پشتیبانی می‌کنند (GeoTIFF، VRT...) سودمند باشد. توجه داشته باشید که مقادیر مشخص‌شده پس از -scale تنها برای محاسبه یک مقیاس و آفست جهت اعمال روی مقادیر رستر ورودی استفاده می‌شوند. به ویژه، src_min و src_max برای برش دادن (clip) مقادیر ورودی استفاده نمی‌شوند مگر اینکه -exponent نیز مشخص شده باشد. به جای بریده شدن، مقادیر منبعی که خارج از بازه src_min و src_max هستند، به مقادیری خارج از بازه dst_min و dst_max مقیاس‌بندی می‌شوند. اگر برش دادن بدون مقیاس‌بندی نمایی مورد نظر باشد، می‌توان از -exponent 1 استفاده کرد. گزینه -scale می‌تواند چندین بار تکرار شود (در صورت مشخص شدنِ تنها یک بار، برای تمام باندهای مجموعه‌داده خروجی نیز اعمال می‌شود) تا پارامترها به ازای هر باند مشخص شوند. همچنین امکان استفاده از ساختار -scale_bn وجود دارد که در آن bn شماره باند است (مانند -scale_2 برای باند دوم مجموعه‌داده خروجی) تا پارامترهای یک یا چند باند خاص تعیین گردند.

-exponent <exp_val>

اعمال مقیاس‌بندی غیرخطی با یک تابع توانی. مقدار exp_val توانِ تابع توانی است (باید مثبت باشد). این گزینه باید همراه با گزینه -scale استفاده شود. اگر تنها یک بار مشخص شود، -exponent برای تمام باندهای تصویر خروجی اعمال می‌شود. این گزینه می‌تواند چندین بار تکرار شود تا پارامترها به ازای هر باند مشخص شوند. همچنین استفاده از ساختار -exponent_bn که در آن bn شماره باند است (مانند -exponent_2 برای باند دوم مجموعه‌داده خروجی) برای تعیین پارامترهای یک یا چند باند مشخص امکان‌پذیر است.

مقدار مقیاس‌شده Dst از مقدار منبع Src با فرمول زیر محاسبه می‌شود:

{Dst} = \left( {Dst}_{max} - {Dst}_{min} \right) \times \operatorname{max} \left( 0, \operatorname{min} \left( 1, \left( \frac{{Src} - {Src}_{min}}{{Src}_{max}-{Src}_{min}} \right)^{exp\_val} \right) \right) + {Dst}_{min}

-unscale

اعمال فراداده مقیاس/آفست (scale/offset) برای باندها جهت تبدیل مقادیر دارای مقیاس خطی به مقادیر بدون مقیاس. همچنین اغلب لازم است که نوع داده خروجی توسط سوییچ -ot بازنشانی شود. مقدار بدون مقیاس از مقدار خام مقیاس‌شده با فرمول زیر محاسبه می‌شود:

{unscaled\_value} = {scaled\_value} * {scale} + {offset}

-srcwin <xoff> <yoff> <xsize> <ysize>

یک پنجره فرعی را برای کپی‌کردن بر اساس موقعیت پیکسل/سطر از تصویر منبع انتخاب می‌کند. آفست‌های پیکسل/سطر (xoff و yoff) از گوشه بالا و سمت چپ تصویر اندازه‌گیری می‌شوند. اگر پنجره فرعی فراتر از محدوده‌های مجموعه‌داده منبع امتداد یابد، پیکسل‌های خروجی با مقدار صفر نوشته خواهند شد، مگر اینکه یک مقدار NoData در مجموعه‌داده منبع یا توسط -a_nodata تعریف شده باشد. در غیر این صورت، چنانچه توسط گزینه‌های -epo یا -eco تعیین شده باشد، دستور gdal_translate می‌تواند در این شرایط یک خطا صادر کند.

-projwin <ulx> <uly> <lrx> <lry>

یک پنجره فرعی را از تصویر منبع برای کپی‌کردن (مشابه -srcwin) انتخاب می‌کند اما با گوشه‌هایی که در مختصات زمین‌مرجع‌شده داده شده‌اند (به طور پیش‌فرض در SRS مجموعه‌داده بیان می‌شود. با -projwin_srs قابل تغییر است). اگر پنجره فرعی فراتر از محدوده‌های مجموعه‌داده منبع امتداد یابد، پیکسل‌های خروجی با مقدار صفر نوشته خواهند شد، مگر اینکه یک مقدار NoData در مجموعه‌داده منبع یا توسط -a_nodata تعریف شده باشد. در غیر این صورت، چنانچه توسط گزینه‌های -epo یا -eco تعیین شده باشد، gdal_translate می‌تواند در این شرایط یک خطا صادر کند.

نکته:

نکته:

-projwin_srs <srs_def>

سیستم مرجع مکانی (SRS) را که مختصات ارائه‌شده با -projwin باید در آن تفسیر شوند مشخص می‌کند. مقدار <srs_def> می‌تواند هر یک از قالب‌های معمول GDAL/OGR، قالب کامل WKT، PROJ.4، EPSG:n یا فایلی حاوی WKT باشد.

هشدار:

-epo

(خطا هنگام قرارگیری جزئی در خارج / Error when Partially Outside) اگر این گزینه تنظیم شود، مقادیر -srcwin یا -projwin که تا حدی خارج از محدوده رستر منبع قرار می‌گیرند، به عنوان خطا در نظر گرفته خواهند شد. رفتار پیش‌فرض پذیرش چنین درخواست‌هایی است.

-a_srs <srs_def>

بازنویسی سیستم تصویر فایل خروجی. می‌تواند همراه با -a_ullr یا -a_gt برای تعیین محدوده در این سیستم تصویر استفاده شود.

سیستم‌های مرجع مختصاتی که می‌توان ارسال کرد، هر موردی است که توسط فراخوانی OGRSpatialReference::SetFromUserInput() پشتیبانی می‌شود؛ از جمله CRSهای تصویرشده، جغرافیایی یا مرکب EPSG (مانند EPSG:4296)، یک تعریف CRS به زبان متن شناخته‌شده (WKT)، اعلان‌های PROJ.4، یا نام یک فایل .prj حاوی تعریف WKT CRS.

نکته:

-a_coord_epoch <epoch>

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

اختصاص یک دوره زمانی مختصات (coordinate epoch)، مرتبط با SRS خروجی. زمانی کاربرد دارد که SRS خروجی یک CRS پویا باشد.

-a_scale <value>

تنظیم مقدار مقیاس‌بندی باند. هیچ تغییری در مقادیر پیکسل‌ها داده نمی‌شود. توجه داشته باشید که -unscale گزینه -a_scale را لحاظ نمی‌کند. برای مثال می‌توانید -scale 0 1 <offset> <offset+scale> را برای اعمال چندتایی (offset, scale) مشخص کنید، به عنوان معادل این ۲ مرحله: gdal_translate input.tif tmp.vrt -a_scale scale -a_offset offset و به دنبال آن gdal_translate tmp.vrt output.tif -unscale

-a_offset <value>

تنظیم مقدار آفست باند. هیچ تغییری در مقادیر پیکسل‌ها داده نمی‌شود. توجه داشته باشید که -unscale گزینه -a_offset را لحاظ نمی‌کند. برای مثال می‌توانید -scale 0 1 <offset> <offset+scale> را برای اعمال چندتایی (offset, scale) مشخص کنید، به عنوان معادل این ۲ مرحله: gdal_translate input.tif tmp.vrt -a_scale scale -a_offset offset و به دنبال آن gdal_translate tmp.vrt output.tif -unscale

-a_ullr <ulx> <uly> <lrx> <lry>

اختصاص/بازنویسی مرزهای زمین‌مرجع فایل خروجی. این گزینه مرزهای زمین‌مرجع را به فایل خروجی اختصاص می‌دهد و آنچه را که از فایل منبع مشتق می‌شد نادیده می‌گیرد. بنابراین این کار باعث تغییر سیستم تصویر به SRS مشخص‌شده نمی‌شود. این گزینه با -a_gt مانعة‌الجمع است.

-a_gt <gt(0)> <gt(1)> <gt(2)> <gt(3)> <gt(4)> <gt(5)>

اختصاص/بازنویسی تبدیل زمین‌مرجع (geotransform) فایل خروجی. این گزینه تبدیل زمین‌مرجع را به فایل خروجی اختصاص می‌دهد و آنچه را که از فایل منبع مشتق می‌شد نادیده می‌گیرد. بنابراین این کار باعث تغییر سیستم تصویر به SRS مشخص‌شده نمی‌شود. به Geotransform Tutorial مراجعه کنید. این گزینه با -a_ullr مانعة‌الجمع است.

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

-a_nodata <value>

اختصاص یک مقدار nodata مشخص به باندهای خروجی. در صورتی که فایل منبع دارای مقدار nodata باشد، این گزینه می‌تواند روی none تنظیم شود تا از اختصاص مقدار nodata به فایل خروجی جلوگیری شود. توجه داشته باشید که اگر مجموعه داده ورودی مقداری برای nodata داشته باشد، این گزینه باعث تغییر مقادیر پیکسلی که برابر با آن مقدار nodata هستند به مقدار مشخص‌شده با این گزینه نمی‌شود.

-colorinterp_X <red|green|blue|alpha|gray|undefined|pan|coastal|rededge|nir|swir|mwir|lwir|...>

بازنویسی تفسیر رنگ باند X (که در آن X شماره باند معتبری است که از ۱ شروع می‌شود).

-colorinterp {red|green|blue|alpha|gray|undefined|pan|coastal|rededge|nir|swir|mwir|lwir|...},...

بازنویسی تفسیر رنگ تمام باندهای مشخص‌شده. برای مثال -colorinterp red,green,blue,alpha برای یک مجموعه داده خروجی ۴ بانده.

-mo <META-TAG>=<VALUE>

ارسال یک کلید و مقدار فراداده (metadata) برای تنظیم روی مجموعه داده خروجی در صورت امکان.

-dmo DOMAIN:META-TAG=VALUE

ارسال یک کلید و مقدار فراداده در دامنه (domain) مشخص‌شده برای تنظیم روی مجموعه داده خروجی در صورت امکان.

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

-co <NAME>=<VALUE>

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

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

علاوه بر گزینه‌های ساخت اختصاصی درایور، ابزار gdal_translate (و GDALTranslate() و GDALCreateCopy()) گزینه‌های زیر را تشخیص می‌دهند:

-nogcp

GCPهای موجود در مجموعه داده منبع در مجموعه داده خروجی کپی نشوند.

-gcp <pixel> <line> <easting> <northing> [<elevation>]

افزودن نقطه کنترل زمینی مشخص‌شده به مجموعه داده خروجی. این گزینه می‌تواند چندین بار برای ارائه مجموعه‌ای از GCPها مشخص شود.

-q

جلوگیری از نمایش ناظر پیشرفت و سایر خروجی‌های غیرخطا.

-sds

کپی کردن تمام زیرمجموعه‌های داده این فایل به فایل‌های خروجی مجزا. برای قالب‌هایی مانند HDF که دارای زیرمجموعه داده (subdataset) هستند استفاده می‌شود.

-norat

عدم کپی RAT منبع در مجموعه‌داده مقصد.

-noxmp

عدم کپی فراداده XMP موجود در مجموعه‌داده منبع به مجموعه‌داده خروجی، زمانی که درایور قادر به کپی آن باشد.

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

-oo <NAME>=<VALUE>

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

<src_dataset>

نام مجموعه‌داده منبع. می‌تواند نام فایل، URL منبع داده یا نام زیرمجموعه‌داده برای فایل‌های چندمجموعه‌داده‌ای باشد.

<dst_dataset>

نام فایل مقصد.

• برای بازنمونه‌برداری nearest، برای هر پیکسل هدف، یکی از پیکسل‌های منبع با احتمال مشارکت (به روشی وابسته به پیاده‌سازی) انتخاب می‌شود. مقدار آن به همان صورت استفاده می‌شود، خواه معتبر باشد یا نامعتبر.
• برای bilinear، cubic، cubicspline و lanczos، برای هر پیکسل هدف، وزن پیکسل‌های منبع مشارکت‌کننده در صورت ماسک بودن روی صفر تنظیم می‌شود تا نادیده گرفته شوند. یک ویژگی خاص دیگر برای cubic و lanczos وجود دارد: با توجه به اینکه برخی از وزن‌ها در هسته منفی هستند، چنین راهبردی می‌تواند در صورت تناوب پیکسل‌های معتبر و نامعتبر منجر به overshoot/undershoot شدیدی شود. در نتیجه، در صورتی که در هر یک از جهات افقی یا عمودی، حداکثر تعداد پیکسل‌های معتبر منبع در هر بُعد کمتر از شعاع هسته بازنمونه‌برداری باشد، پیکسل هدف به عنوان nodata در نظر گرفته می‌شود.
• برای سایر روش‌های بازنمونه‌برداری، پیکسل‌های منبع مشارکت‌کننده در پیکسل هدف در صورت ماسک بودن نادیده گرفته می‌شوند. تنها پیکسل‌های معتبر در نظر گرفته می‌شوند. در صورتی که هیچ پیکسلی وجود نداشته باشد، پیکسل هدف به عنوان nodata لحاظ می‌شود.