نام (NAME)

gdal-raster-create - ایجاد یک مجموعه‌داده رستر جدید

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

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

Usage: gdal raster create [OPTIONS] <OUTPUT>
ایجاد یک مجموعه‌داده رستر جدید.
آرگومان‌های مکانی:
  -o, --output <OUTPUT>                                    مجموعه‌داده رستر خروجی [الزامی] [در خطوط لوله در دسترس نیست]
گزینه‌های عمومی:
  -h, --help                                               نمایش پیام راهنما و خروج
  --json-usage                                             نمایش نحوه استفاده در قالب سند JSON و خروج
  --config <KEY>=<VALUE>                                   گزینه پیکربندی [تکرارپذیر]
  -q, --quiet                                              حالت بی‌صدا (بدون نوار پیشرفت یا پیام هشدار) [در خطوط لوله در دسترس نیست]
گزینه‌ها:
  -i, --like, --input <TEMPLATE-DATASET>                   مجموعه‌داده رستر الگو [در خطوط لوله در دسترس نیست]
  -f, --of, --format, --output-format <OUTPUT-FORMAT>      قالب خروجی (مقدار "GDALG" مجاز است) [در خطوط لوله در دسترس نیست]
  --co, --creation-option <KEY>=<VALUE>                    گزینه ایجاد [تکرارپذیر] [در خطوط لوله در دسترس نیست]
  --overwrite                                              امکان بازنویسی مجموعه‌داده خروجی موجود [در خطوط لوله در دسترس نیست]
                                                           ناسازگار با --append
  --append                                                 الحاق به عنوان زیرمجموعه‌داده به خروجی موجود [در خطوط لوله در دسترس نیست]
                                                           ناسازگار با --overwrite
  --size <width>,<height>                                  اندازه خروجی بر حسب پیکسل
  --band-count <BAND-COUNT>                                تعداد باندها (پیش‌فرض: 1)
  --ot, --datatype, --output-data-type <OUTPUT-DATA-TYPE>  نوع داده خروجی. OUTPUT-DATA-TYPE=UInt8|Int8|UInt16|Int16|UInt32|Int32|UInt64|Int64|CInt16|CInt32|Float16|Float32|Float64|CFloat32|CFloat64 (پیش‌فرض: Byte)
  --nodata <NODATA>                                        انتساب یک مقدار nodata مشخص به باندهای خروجی ('none'، مقدار عددی، 'nan'، 'inf'، '-inf')
  --burn <BURN>                                            مقدار ثبت / سوزاندن (burn value) [تکرارپذیر]
  --crs <CRS>                                              تنظیم CRS
  --bbox <BBOX>                                            جعبه محدودکننده به صورت xmin,ymin,xmax,ymax
  --metadata <KEY>=<VALUE>                                 افزودن آیتم متادیتا [تکرارپذیر]
  --copy-metadata                                          کپی متادیتا از مجموعه‌داده ورودی
                                                           وابسته به --input
  --copy-overviews                                         ایجاد سطوح پیش‌نمایش مشابه مجموعه‌داده ورودی
                                                           وابسته به --input
گزینه‌های پیشرفته:
  --if, --input-format <INPUT-FORMAT>                      قالب‌های ورودی [تکرارپذیر] [در خطوط لوله در دسترس نیست]
  --oo, --open-option <KEY>=<VALUE>                        گزینه‌های باز کردن [تکرارپذیر] [در خطوط لوله در دسترس نیست]

توضیحات (DESCRIPTION)

دستور gdal raster create می‌تواند برای مقداردهی اولیه یک فایل رستر جدید بر اساس ابعاد، تعداد باند، CRS، تبدیل زمین‌مرجع (geotransform)، مقدار nodata و متادیتای آن استفاده شود.

همچنین می‌توان فایل جدید را از یک فایل ورودی الگو با استفاده از گزینه اختیاری --like مقداردهی کرد، که ویژگی‌های آن را بدون کپی کردن مقادیر پیکسل‌ها کپی می‌کند. به طور پیش‌فرض، متادیتا و ساختار پیش‌نمایش (overview) از فایل الگوی ورودی کپی نمی‌شوند، مگر اینکه گزینه‌های --copy-metadata و --copy-overviews مشخص شده باشند. گزینه‌های --size، --band-count، --datatype، --nodata، --crs، --bbox و --metadata می‌توانند برای لغو مقادیر به ارث رسیده از فایل الگوی ورودی استفاده شوند.

برای خروجی GeoTIFF، تنظیم گزینه ایجاد SPARSE_OK به YES می‌تواند برای ایجاد فایلی با حداقل اندازه مفید باشد.

دستور gdal raster create همچنین در موارد خاصی مانند ایجاد یک فایل PDF از روی یک فایل ترکیب XML قابل استفاده است.

از نسخه GDAL 3.13 به بعد، create می‌تواند به عنوان یک مرحله از gdal raster pipeline نیز به کار رود.

گزینه‌های اختصاصی برنامه (PROGRAM-SPECIFIC OPTIONS)

--band-count <count>: تعداد باندها. پیش‌فرض 1 است.

--bbox <xmin>,<ymin>,<xmax>,<ymax>: تنظیم جعبه محدودکننده مکانی، بر حسب واحدهای CRS. 'x' مقادیر طول جغرافیایی برای CRS جغرافیایی و مختصات شرقی برای CRS تصویرشده است. 'y' مقادیر عرض جغرافیایی برای CRS جغرافیایی و مختصات شمالی برای CRS تصویرشده است.

--burn <value>: یک مقدار ثابت جهت ثبت و سوزاندن (burn) در یک باند. فهرستی از گزینه‌های --burn می‌تواند ارائه شود، به ازای هر باند یک مقدار (مقدار اول روی باند اول، مقدار دوم روی باند دوم و غیره اعمال می‌شود). اگر یک مقدار واحد مشخص شود، روی تمامی باندها اعمال خواهد شد.

--copy-metadata: کپی متادیتا از مجموعه‌داده ورودی و باندهای رستر. نیازمند مشخص شدن --like است.

--copy-overviews: ایجاد سطوح پیش‌نمایش مشابه مجموعه‌داده ورودی (اما با محتوای خالی). نیازمند مشخص شدن --like است.

--crs <CRS>

تنظیم سامانه مرجع مختصات (CRS).

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

برای لغو CRS موجود در مجموعه‌داده --like (در صورت تنظیم بودن آن)، می‌توان مقدار null یا none را مشخص کرد.

توجه داشته باشید که وسعت مکانی نیز بدون تغییر باقی می‌ماند.

-i, --like, --input <TEMPLATE-DATASET>: نام مجموعه‌داده ورودی GDAL که به عنوان الگو برای مقادیر پیش‌فرض گزینه‌های --size، --band-count، --datatype، --crs، --bbox و --nodata عمل می‌کند. توجه داشته باشید که مقادیر پیکسل‌ها کپی نخواهند شد.
از نسخه GDAL 3.13، در صورتی که مجموعه‌داده ورودی تایل‌بندی شده باشد، و برای قالب‌های خروجی GTiff، COG و GPKG، ابعاد تایل‌های آن در فایل خروجی تکرار می‌شود، مشروط بر آنکه با قابلیت‌های آن سازگار باشد و کاربر هیچ گزینه ایجادی مربوط به تایل‌بندی را مشخص نکرده باشد.

--metadata <KEY>=<VALUE>: افزودن یک آیتم متادیتا در سطح مجموعه‌داده.

--nodata <value>: تنظیم مقدار nodata.
برای لغو مقدار nodata موجود در مجموعه‌داده --like (در صورت تنظیم بودن آن)، می‌توان مقدار null یا none را مشخص کرد. همچنین مقادیر nan، inf یا -inf برای رسترهای ممیز شناور پذیرفته می‌شوند که به ترتیب به معنای مقادیر ویژه تعریف‌نشده (not-a-number)، بی‌نهایت مثبت و بی‌نهایت منفی هستند.

--size <xsize>,<ysize>: تنظیم اندازه فایل خروجی بر حسب پیکسل. مقدار اول عرض و مقدار دوم ارتفاع است.

گزینه‌های استاندارد (STANDARD OPTIONS)

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

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

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

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

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

--if, --input-format <format>: نام قالب یا درایور جهت تلاش برای باز کردن فایل یا فایل‌های ورودی. به طور کلی مشخص کردن آن الزامی نیست، اما می‌توان از آن برای چشم‌پوشی از تشخیص خودکار درایور، در زمان‌هایی که در انتخاب درایور مناسب ناموفق است، استفاده کرد. این گزینه می‌تواند چندین بار برای تعیین چندین درایور کاندید تکرار شود. توجه داشته باشید که این گزینه آن درایورها را به باز کردن مجموعه‌داده مجبور نمی‌کند؛ به ویژه برخی درایورها الزامات خاصی روی پسوند فایل دارند.
می‌تواند تکرار شود.

--oo, --open-option <NAME>=<VALUE>: گزینه باز کردن مجموعه‌داده (وابسته به قالب).
می‌تواند تکرار شود.

--ot, --datatype, --output-data-type <OUTPUT-DATA-TYPE>: نوع داده خروجی از میان Byte، Int8، UInt16، Int16، UInt32، Int32، UInt64، Int64، CInt16، CInt32، Float32، Float64، CFloat32 و CFloat64.

-f, --of, --format, --output-format <OUTPUT-FORMAT>: تعیین قالب رستر خروجی مورد استفاده. مقادیر مجاز با اجرای دستور زیر قابل مشاهده است: gdal --formats | grep raster | grep + | sort

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

کد وضعیت بازگشتی (RETURN STATUS CODE)

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

مثال‌ها (EXAMPLES)

مثال ۱: مقداردهی اولیه یک فایل GeoTIFF جدید با ۳ باند و مقدار یکنواخت ۱۰

gdal raster create --size=20,20 --band-count=3 --crs=EPSG:4326 --bbox=2,49,3,50 --burn 10 out.tif

مثال ۲: ایجاد یک فایل PDF از روی یک فایل ترکیب XML

gdal raster create --creation-option COMPOSITION_FILE=composition.xml out.pdf

مثال ۳: مقداردهی اولیه یک فایل GeoTIFF خام از روی یک فایل ورودی

gdal raster create --like prototype.tif output.tif

نویسنده (AUTHOR)

Even Rouault <even.rouault@spatialys.com>

حق نشر (COPYRIGHT)

1998-2026