GDAL-RASTER-PIXEL-INFO(1)

GDAL

GDAL-RASTER-PIXEL-INFO(1)

نام (NAME)

gdal-raster-pixel-info - بازگرداندن اطلاعات مربوط به یک پیکسل از مجموعه‌داده رستر

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

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

کاربرد: gdal raster pixel-info [OPTIONS] <INPUT> [<column,line> یا <X,Y>]
بازگرداندن اطلاعات مربوط به یک پیکسل از مجموعه‌داده رستر.
آرگومان‌های موضعی:
  -i, --dataset, --input <INPUT>                       مجموعه‌داده‌های رستر ورودی [الزامی]
  -p, --pos, --position <column,line> or <X,Y>         موقعیت پیکسل [ممکن است تکرار شود]
                                                       مانعه‌الجمع با --position-dataset
گزینه‌های عمومی:
  -h, --help                                           نمایش پیام راهنما و خروج
  --json-usage                                         نمایش نحوه استفاده به صورت سند JSON و خروج
  --config <KEY>=<VALUE>                               گزینه پیکربندی [ممکن است تکرار شود]
گزینه‌ها:
  -f, --of, --format, --output-format <OUTPUT-FORMAT>  قالب خروجی (پیش‌فرض 'GeoJSON' است اگر 'position-dataset' مشخص نشده باشد) [در خط‌لوله‌ها در دسترس نیست]
  --position-dataset <POSITION-DATASET>                مجموعه‌داده برداری حاوی مختصات
                                                       مانعه‌الجمع با --position
  -l, --layer, --input-layer <INPUT-LAYER>             نام لایه ورودی
  -o, --output <OUTPUT>                                مجموعه‌داده برداری خروجی (ایجاد شده توسط الگوریتم)
  --co, --creation-option <KEY>=<VALUE>                گزینه ساخت [ممکن است تکرار شود] [در خط‌لوله‌ها در دسترس نیست]
  --lco, --layer-creation-option <KEY>=<VALUE>         گزینه ساخت لایه [ممکن است تکرار شود] [در خط‌لوله‌ها در دسترس نیست]
  --overwrite                                          مجاز بودن بازنویسی مجموعه‌داده خروجی موجود [در خط‌لوله‌ها در دسترس نیست]
  -b, --band <BAND>                                    باند(های) ورودی (شاخص بر پایه ۱) [ممکن است تکرار شود]
  --overview <OVERVIEW>                                کدام سطح نمای کلی (overview) از فایل مبدأ باید استفاده شود
  --position-crs <POSITION-CRS>                        CRS موقعیت (پیش‌فرض 'pixel' است اگر 'position-dataset' مشخص نشده باشد)
  -r, --resampling <RESAMPLING>                        الگوریتم بازنمونه‌برداری برای درون‌یابی. RESAMPLING=nearest|bilinear|cubic|cubicspline (پیش‌فرض: nearest)
  --promote-pixel-value-to-z                           تنظیم مقدار پیکسل به عنوان مؤلفه Z در هندسه GeoJSON
  --include-field <INCLUDE-FIELD>                      فیلدهایی از مجموعه‌داده مختصات جهت درج در خروجی (مقادیر ویژه: ALL و NONE) (پیش‌فرض: ALL) [ممکن است تکرار شود]
گزینه‌های پیشرفته:
  --oo, --open-option <KEY>=<VALUE>                    گزینه‌های باز کردن [ممکن است تکرار شود] [در خط‌لوله‌ها در دسترس نیست]
  --if, --input-format <INPUT-FORMAT>                  قالب‌های ورودی [ممکن است تکرار شود] [در خط‌لوله‌ها در دسترس نیست]

توضیحات (DESCRIPTION)

دستور gdal raster pixel-info سازوکاری را برای پرس‌وجوی اطلاعات یک پیکسل با توجه به موقعیت مکانی آن در یکی از انواع سامانه‌های مختصات فراهم می‌کند.

موارد زیر (در صورت مشخص بودن) گزارش خواهند شد:

مختصات ورودی
مختصات ورودی تبدیل‌شده به ستون، سطر
مقدار پیکسل به ازای هر باند انتخاب‌شده، همراه با مقدار مقیاس‌بندی‌نشده
برای فایل‌های VRT، این‌که کدام فایل(ها) در مقدار پیکسل نقش دارند (تنها برای خروجی GeoJSON)

۳ روش ممکن برای ارائه موقعیت(های) ورودی وجود دارد:

از جریان ورودی، با یک جفت "X Y" در هر خط، که احتمالاً متن‌های دیگری نیز به دنبال آن می‌آید.
از طریق آرگومان --position.
از طریق یک مجموعه‌داده برداری GDAL با استفاده از آرگومان --position-dataset.

۲ حالت ممکن برای خروجی دادن اطلاعات پیکسل وجود دارد:

یا در جریان خروجی به صورت CSV یا GeoJSON (پیش‌فرض GeoJSON است)
یا به عنوان یک مجموعه‌داده برداری GDAL که نام آن با آرگومان --output مشخص می‌شود.

از نسخه GDAL 3.13، این الگوریتم می‌تواند بخشی از یک gdal pipeline باشد. در این حالت، تنها خواندن مختصات از یک مجموعه‌داده برداری GDAL و ارسال نتایج خروجی به آن پشتیبانی می‌شود.

اضافه‌شده در نسخه 3.13..SH "خروجی GDALG (مجموعه‌داده در لحظه / جریانی) (GDALG OUTPUT (ON-THE-FLY / STREAMED DATASET))"

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

نکته:

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

گزینه‌های زیر در دسترس هستند:

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

-b <band>: باندی را برای پرس‌وجو انتخاب می‌کند. چندین باند را می‌توان مشخص کرد. به‌طور پیش‌فرض، همه باندها پرس‌وجو می‌شوند.

-f, --of, --format, --output-format <FORMAT>: کدام فرمت خروجی برداری استفاده شود.
هنگامی که --output مشخص نشده باشد، csv یا geojson تنها دو گزینه پشتیبانی‌شده هستند که geojson پیش‌فرض است. در غیر این صورت، هر فرمت برداری پشتیبانی‌شده توسط GDAL با قابلیت نوشتن، پشتیبانی می‌شود.

--position-dataset <COORDINATE-DATASET>

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

مجموعه‌داده برداری سازگار با GDAL که مختصات ورودی از آن خوانده می‌شود. اگر عارضه ورودی دارای هندسه نقطه‌ای باشد، از موقعیت آن برای پرس‌وجوی رستر استفاده می‌شود. برای سایر انواع هندسه، از مرکزوار (centroid) استفاده می‌شود. برای خواندن تمام مقادیر پیکسل برای هندسه‌های غیرنقطه‌ای، از gdal raster zonal-stats استفاده کنید. به‌طور پیش‌فرض، تمام فیلدهای توصیفی در خروجی کپی می‌شوند.

اگر آرگومان --position-crs مشخص شده باشد، مختصات نقطه مطابق با مقدار آن آرگومان تفسیر می‌شود.

در غیر این صورت، اگر لایه برداری ورودی دارای CRS باشد، فرض می‌شود که مختصات در آن بیان شده است.

در غیر این صورت، فرض می‌شود مختصات در CRS مجموعه‌داده رستر است، چنانچه دارای CRS باشد.

در غیر این صورت، فرض می‌شود مختصات در فضای سطر،ستون رستر بیان شده است.

-l, --layer, --input-layer <INPUT-LAYER>: در نسخه 3.13 اضافه شد.
نام لایه ورودی از مجموعه‌داده مشخص‌شده با --position-dataset برای استفاده.

-o, --output <OUTPUT>: در نسخه 3.13 اضافه شد.
مجموعه‌داده برداری خروجی (ایجادشده توسط الگوریتم)

--include-field <FIELD>: در نسخه 3.13 اضافه شد.
نام فیلد(ها) از --position-dataset برای گنجاندن در خروجی. به‌طور پیش‌فرض، تمام فیلدها گنجانده می‌شوند (که متناظر با مقدار ویژه ALL است). می‌توان از مقدار ویژه NONE استفاده کرد تا هیچ فیلدی از مجموعه‌داده موقعیت در خروجی گنجانده نشود.

--ovr, --overview <index>: پرس‌وجوی پیش‌نمای (overview_level)ام (overview_level=0 نخستین پیش‌نما است)، به‌جای باند پایه. توجه داشته باشید که موقعیت x,y (چنانچه سیستم مختصات پیکسل/خط باشد) همچنان باید نسبت به باند پایه مشخص شود.

-p, --pos, --position <column,line> or <X,Y>

الزامی است، در صورتی که --position-dataset مشخص نشده باشد و هیچ محتوایی از طریق جریان ورودی ارائه نشود.

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

به‌طور پیش‌فرض، هنگامی که --position-crs مشخص نشده باشد یا روی pixel تنظیم شده باشد، این مقدار یک چندتایی ستون، سطر است (احتمالاً دارای بخش اعشاری). اگر --position-crs روی dataset تنظیم شده باشد، این یک مختصات زمین‌مرجع بیان‌شده در CRS مجموعه‌داده است. اگر --position-crs روی یک تعریف CRS تعیین شده باشد، این یک مختصات زمین‌مرجع بیان‌شده در این CRS خواهد بود.

همواره X به معنای طول جغرافیایی یا شرق‌سو، و Y به معنای عرض جغرافیایی یا شمال‌سو است.

می‌توان چندین چندتایی x,y را مشخص کرد.

--position-crs pixel|dataset|<crs-def>: سیستم مرجع مختصات (CRS) موقعیت، یا یکی از دو مقدار ویژه زیر:

pixel یعنی موقعیت به‌صورت ستون، سطر تعیین شده است (پیش‌فرض)
dataset یعنی موقعیت یک مختصات زمین‌مرجع بیان‌شده در CRS مجموعه‌داده است.

--promote-pixel-value-to-z: در نسخه 3.13 اضافه شد.
تعیین می‌کند که آیا مقدار پیکسل به‌عنوان مؤلفه Z هندسه GeoJSON تنظیم شود یا خیر. تنها در صورتی اعمال می‌شود که یک باند منفرد انتخاب شده باشد، و برای فرمت خروجی GeoJSON است.

-r, --resampling nearest|bilinear|cubic|cubicspline: یک الگوریتم نمونه‌برداری را انتخاب می‌کند. پیش‌فرض nearest است.
روش‌های موجود عبارتند از:

nearest روش نزدیک‌ترین همسایه را اعمال می‌کند.
bilinear یک هسته پیچش دوخطی را اعمال می‌کند.
cubic یک هسته پیچش درجه سه را اعمال می‌کند.
cubicspline یک هسته پیچش B-Spline را اعمال می‌کند.

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

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

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

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

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

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

--lco, --layer-creation-option <NAME>=<VALUE>

بسیاری از قالب‌ها یک یا چند گزینه اختیاری ساخت لایه دارند که می‌توان از آن‌ها برای کنترل جزئیات لایه ایجادشده استفاده کرد. به عنوان مثال، درایور GeoPackage از گزینه‌های ساخت لایه برای کنترل شناسه عارضه یا نام ستون هندسه، تنظیم شناسه یا توضیحات و موارد دیگر پشتیبانی می‌کند.

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

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

توجه داشته باشید که گزینه‌های ساخت لایه با گزینه‌های ساخت مجموعه داده متفاوت هستند.

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

وضعیت خروج (EXIT STATUS)

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

مثال‌ها (EXAMPLES)

مثال ۱: گزارش در مورد پیکسل column=5، line=10 روی فایل byte.tif

$ gdal raster pixel-info byte.tif 5 10
{
  "type":"FeatureCollection",
  "crs":{
    "type":"name",
    "properties":{
      "name":"urn:ogc:def:crs:EPSG::26711"
    }
  },
  "features":[
    {
      "type":"Feature",
      "properties":{
        "input_coordinate":[
          5.0,
          10.0
        ],
        "column":5.0,
        "line":10.0,
        "bands":[
          {
            "band_number":1,
            "raw_value":132,
            "unscaled_value":132.0
          }
        ]
      },
      "geometry":{
        "type":"Point",
        "coordinates":[
          441020.0,
          3750720.0
        ]
      }
    }
  ]
}

$ gdal raster pixel-info --position-crs=dataset byte.tif 441320 3750720
{
  "type":"FeatureCollection",
  "crs":{
    "type":"name",
    "properties":{
      "name":"urn:ogc:def:crs:EPSG::26711"
    }
  },
  "features":[
    {
      "type":"Feature",
      "properties":{
        "input_coordinate":[
          441320.0,
          3750720.0
        ],
        "column":10.0,
        "line":10.0,
        "bands":[
          {
            "band_number":1,
            "raw_value":115,
            "unscaled_value":115.0
          }
        ]
      },
      "geometry":{
        "type":"Point",
        "coordinates":[
          441320.0,
          3750720.0
        ]
      }
    }
  ]
}

مثال ۳: گزارش نقطه در مختصات WGS84 با longitude=-117.6355 و latitude=33.8970 روی فایل byte.tif، با قالب خروجی CSV

$ gdal raster pixel-info --of=csv --position-crs=WGS84 byte.tif -117.6355 33.8970
geom_x,geom_y,extra_content,column,line,band_1_raw_value,band_1_unscaled_value
-117.6355,33.897,,10.020546288988,9.98330473474925,115,115

مثال ۴: گزارش نقطه در مختصات WGS84 داده‌شده از ورودی استاندارد به ترتیب longitude و latitude.

$ echo -117.6355 33.8970 | gdal raster pixel-info --of=csv --position-crs=WGS84 byte.tif
geom_x,geom_y,extra_content,column,line,band_1_raw_value,band_1_unscaled_value
-117.6355,33.897,,10.020546288988,9.98330473474925,115,115

مثال ۵: خواندن مختصات برای استخراج از یک فایل ورودی GeoPackage و نوشتن خروجی در یک فایل GeoPackage

gdal raster pixel-info --position-dataset input.gpkg --input byte.tif --output output.gpkg

مثال ۶: دریافت مقادیر پیکسل از یک مجموعه‌داده رستری تغییر اندازه یافته به‌صورت درجا (on-the-fly) بر اساس مختصات موجود در input.gpkg.

gdal pipeline read byte.tif ! resize --size 50%,50% -r cubic ! pixel-info input.gpkg ! write output.gpkg

gdal pipeline read input.gml ! swap-xy ! pixel-info --input byte.tif --position-dataset _ ! write output.gpkg

نویسندگان (AUTHORS)

Even Rouault <even.rouault@spatialys.com>

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

1998-2026

August 18, 2026