pkextractogr(1)

💖 NAME 💖

okay bestie, so this is pkextractogr(1), and she does exactly one thing but she does it so well: extract pixel values from a raster image, using a sample that can be vector or raster 💅

---

✨ SYNOPSIS ✨

pkextractogr -i input [-s sample | -rand number | -grid size] -o output
             [options]

like, that's the whole vibe in one line. -i in, -o out, and you pick how you sample in the middle 🎀

---

🌸 DESCRIPTION 🌸

okay so here's the tea 🍓 pkextractogr pulls pixel values out of an input raster dataset, and it does it based on the locations you hand it in a sample file. but wait, there's more: if you don't have a sample lying around, you can also get a random sample or a systematic grid of points extracted instead. no sample? no problem. 👑

the sample itself can be a vector file with points or polygons. and if you're working with polygons, you've got options, bestie:

• extract the values for all raster pixels that the polygons cover, or
• extract a single value for each polygon — like the centroid, mean, median, etc.

as output, you get a brand-new copy of the vector file, with an extra attribute holding the extracted pixel value. and not just one attribute — for each raster band in the input image, a separate attribute gets created. so if your raster dataset has three bands, you get three attributes, and their names are b0, b1 and b2. cute, consistent, iconic 💖

a typical usage of pkextractogr is to prepare a training sample for one of the classifiers implemented in pktools. iykyk.

🌈 Overview of the possible extraction rules 🌈

here's the full menu, no substitutions, no skipping:

• point — Extract all pixel values covered by the polygon (option -polygon not set) or extract a pixel on the surface option (-polygon set).
• allpoints — Extract all pixel values covered by the polygon.
• centroid — Extract pixel value at the centroid of the polygon.
• mean — Extract average of all pixel values within the polygon.
• stdev — Extract standard deviation of all pixel values within the polygon.
• median — Extract median of all pixel values within the polygon.
• min — Extract minimum value of all pixels within the polygon.
• max — Extract maximum value of all pixels within the polygon.
• sum — Extract sum of the values of all pixels within the polygon.
• mode — Extract the mode of classes within the polygon (classes must be set with the option class).
• proportion — Extract proportion of class(es) within the polygon (classes must be set with the option class).
• count — Extract count of class(es) within the polygon (classes must be set with the option class).
• percentile — Extract percentile as defined by option perc (e.g, 95th percentile of values covered by polygon).

---

🎀 OPTIONS 🎀

every single one of them, bestie. nothing left out, nothing merged, we're thorough in this house 💅

• -i filename, --input filename — Raster input dataset containing band information
• -s sample, --sample sample — OGR vector dataset with features to be extracted from input data. Output will contain features with input band information included. Sample image can also be GDAL raster dataset.
• -ln layer, --ln layer — Layer name(s) in sample (leave empty to select all)
• -rand number, --random number — Create simple random sample of points. Provide number of points to generate
• -grid size, --grid size — Create systematic grid of points. Provide cell grid size (in projected units, e.g,. m)
• -o filename, --output filename — Output sample dataset Output sample dataset (yes she said it twice, and honestly? she's right 🫶)
• -c class, --class class — Class(es) to extract from input sample image. Leave empty to extract all valid data pixels from sample dataset. Make sure to set classes if rule is set to mode, proportion or count.
• -t threshold, --threshold threshold — Probability threshold for selecting samples (randomly). Provide probability in percentage (>0) or absolute (<0). Use a single threshold per vector sample layer. If using raster land cover maps as a sample dataset, you can provide a threshold value for each class (e.g. -t 80 -t 60). Use value 100 to select all pixels for selected class(es)
• -perc percentile, --perc percentile — Percentile value used for rule percentile
• -f format, --f format — Output sample dataset format
• -ft fieldType, --ftype fieldType — Field type (only Real or Integer)
• -lt labelType, --ltype labelType — Label type: In16 or String
• -b band, --band band — Band index(es) to extract. Leave empty to use all bands
• -sband band, --startband band — Start band sequence number
• -eband band, --endband band — End band sequence number
• -r rule, --rule rule — Rule how to report image information per feature (only for vector sample). point (value at each point or at centroid if polygon), centroid, mean, stdev, median, proportion, count, min, max, mode, sum, percentile.
• -bndnodata band, --bndnodata band — Band(s) in input image to check if pixel is valid (used for srcnodata)
• -srcnodata value, --srcnodata value — Invalid value(s) for input image
• -tp threshold, --thresholdPolygon threshold — (absolute) threshold for selecting samples in each polygon
• -buf value, --buffer value — Buffer for calculating statistics for point features
• -circ, --circular — Use a circular disc kernel buffer (for vector point sample datasets only, use in combination with buffer option)
• -v level, --verbose level — Verbose mode if > 0

🫶 friendly reminder from your girl: -r only does its thing for a vector sample, and -circ is for vector point sample datasets only — use it with the buffer option, not on its own. and -c classes are mandatory the second you pick mode, proportion or count. you got this 💜

---

xoxo, that's the whole pkextractogr(1) page, dated 01 January 2025 💜 go extract something gorgeous, bestie ✨🦋🌸