From 66a4e42adc6639bf0c1e9a8a3ae813d6080cc995 Mon Sep 17 00:00:00 2001 From: Weblate Date: Wed, 25 Jan 2023 09:16:07 +0000 Subject: [PATCH] Update translation files Updated by "Update PO files to match POT (msgmerge)" hook in Weblate. Update translation files Updated by "Update PO files to match POT (msgmerge)" hook in Weblate. Update translation files Updated by "Update PO files to match POT (msgmerge)" hook in Weblate. Update translation files Updated by "Update PO files to match POT (msgmerge)" hook in Weblate. Co-authored-by: Weblate Translate-URL: https://weblate.osgeo.org/projects/postgis-workshop/rasters/ Translation: postgis-workshop/rasters --- .../sources/locale/de/LC_MESSAGES/rasters.po | 684 +++++++++++++++--- .../sources/locale/es/LC_MESSAGES/rasters.po | 684 +++++++++++++++--- .../sources/locale/ja/LC_MESSAGES/rasters.po | 684 +++++++++++++++--- .../sources/locale/ko/LC_MESSAGES/rasters.po | 684 +++++++++++++++--- 4 files changed, 2264 insertions(+), 472 deletions(-) diff --git a/postgis-intro/sources/locale/de/LC_MESSAGES/rasters.po b/postgis-intro/sources/locale/de/LC_MESSAGES/rasters.po index 376b773e..17cd270b 100644 --- a/postgis-intro/sources/locale/de/LC_MESSAGES/rasters.po +++ b/postgis-intro/sources/locale/de/LC_MESSAGES/rasters.po @@ -9,7 +9,7 @@ msgid "" msgstr "" "Project-Id-Version: Introduction to PostGIS 1.1\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2023-01-13 00:30-0500\n" +"POT-Creation-Date: 2023-01-25 04:15-0500\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" @@ -31,378 +31,826 @@ msgstr "" msgid "Although pretty pictures such as those you see on your TV screen are rasters, rasters may not be that exciting to look at. In a nutshell, a raster is a matrix, pinned on a coordinate system, that has values that can represent anything you want them to represent." msgstr "" -#: ../../en/rasters.rst:15 -msgid "Since rasters live in cartesian space, rasters can interact with geometries. PostGIS offers many functions that take as input both rasters and geometries. Also many operations applied to rasters will result in geometries. Common ones are the `ST_Polygon`, `ST_Envelope`, `ST_ConvexHull`, and `ST_MinConvexHull` as shown below." +#: ../../en/rasters.rst:17 +msgid "Since rasters live in cartesian space, rasters can interact with geometries. PostGIS offers many functions that take as input both rasters and geometries. Many operations applied to rasters will result in geometries. Common ones are the `ST_Polygon`, `ST_Envelope`, `ST_ConvexHull`, and `ST_MinConvexHull` as shown below. When you cast a raster to a geometry, what is output is the `ST_ConvexHull` of the raster." msgstr "" -#: ../../en/rasters.rst:21 -msgid "The raster format is commonly used to store elevation data, temperature data, satellite data, and thematic data representing things like environmental contamination, population density, and environmental hazard occurrences." +#: ../../en/rasters.rst:24 +msgid "The raster format is commonly used to store elevation data, temperature data, satellite data, and thematic data representing things like environmental contamination, population density, and environmental hazard occurrences. You can use rasters to store any numeric data that has a meaningful coordinate location. The only restriction is that for all data in a specific band the numeric data types have to be the same." msgstr "" -#: ../../en/rasters.rst:23 -msgid "Although raster data can be created from scratch in PostGIS, a more common approach is to load raster data from various formats using the `raster2pgsql `_ command line tool packaged with PostGIS. Before all of that, you must enable raster support in your database by running the command:" +#: ../../en/rasters.rst:28 +msgid "Although raster data can be created from scratch in PostGIS, a more common approach is to load raster data from various formats using the :command:`raster2pgsql` command line tool packaged with PostGIS. Before all of that, you must enable raster support in your database by running the command:" msgstr "" -#: ../../en/rasters.rst:30 +#: ../../en/rasters.rst:37 msgid "Creating Rasters From Geometries" msgstr "" -#: ../../en/rasters.rst:31 +#: ../../en/rasters.rst:38 msgid "We'll start off by first creating raster data from vector data, and then move on to the more exciting approach of loading data from a raster source. You will find that raster data is available in abundance and often free from various government sites." msgstr "" -#: ../../en/rasters.rst:34 +#: ../../en/rasters.rst:41 msgid "We'll start by converting some geometries into rasters using `ST_AsRaster `_ function as follows." msgstr "" -#: ../../en/rasters.rst:48 -msgid "The above example CREATEs a table (**rasters**) from geometries formed from letters using the PostGIS 3.2+ `ST_Letters `_ function. Rasters similar to geometries, can take advantage of spatial indexes. The spatial index used for raster is a functional index that indexes the geometry convexhull of the raster. When loading data with :command:`raster2pgsql` with the :command:`I` switch, the :command:`CREATE INDEX` step is done for you." +#: ../../en/rasters.rst:55 +msgid "The above example CREATEs a table (**rasters**) from geometries formed from letters using the PostGIS 3.2+ `ST_Letters `_ function. Rasters similar to geometries, can take advantage of spatial indexes. The spatial index used for raster is a functional index that indexes the geometry convexhull of the raster." msgstr "" -#: ../../en/rasters.rst:53 -msgid "You can see some useful metadata of your rasters with the following query which utilizes the postgis raster functions `ST_Count `_ function to count the number of pixels that have data and the `ST_MetaData `_ function to provide all sorts of useful background info for our rasters." +#: ../../en/rasters.rst:58 +msgid "You can see some useful metadata of your rasters with the following query which utilizes the postgis raster `ST_Count `_ function to count the number of pixels that have data and the `ST_MetaData `_ function to provide all sorts of useful background info for our rasters." msgstr "" -#: ../../en/rasters.rst:71 -msgid "There are two levels of raster functions. There are functions such as ST_MetaData that work at the raster level and there are functions such as :command:`ST_Count` function and :command:`ST_BandMetaData `_ function that work at the band level. Most functions in postgis raster that work at the band level, work with only one band at a time, and assume the band you want is `1`." +#: ../../en/rasters.rst:76 +msgid "There are two levels of raster functions. There are functions such as ST_MetaData that work at the raster level and there are functions such as :command:`ST_Count` function and `ST_BandMetaData `_ function that work at the band level. Most functions in postgis raster that work at the band level, work with only one band at a time, and assume the band you want is `1`." msgstr "" -#: ../../en/rasters.rst:78 +#: ../../en/rasters.rst:83 +msgid "If you have a multi-band raster, and you need to count the pixel not no-data values in a band other than 1, you would explicitly specify the band number as follows `ST_Count(rast,2)`." +msgstr "" + +#: ../../en/rasters.rst:85 msgid "Note how all the rasters have a 150x150 dimension. This is not ideal. This means that in order to force that, our rasters, are squished in all sorts of ways. If only we could see the ugliness of the rasters before us." msgstr "" -#: ../../en/rasters.rst:81 -msgid "If you have a multi-band raster, and you need to count the pixel not no-data values in a band other than 1, you would explicitly specify the band number as follows `ST_Count(rast,2)`." +#: ../../en/rasters.rst:89 +msgid "Loading Rasters using raster2pgsql" msgstr "" -#: ../../en/rasters.rst:85 +#: ../../en/rasters.rst:90 +msgid "`raster2pgsql `_ is a command-line tool often packaged with PostGIS. If you are on windows and used application stackbuilder PostGIS Bundle, you'll find :command:`raster2pgsql.exe` in the folder ``C:\\Program Files\\PostgreSQL\\15\\bin`` where the *15* should be replaced with the version of PostgreSQL you are running." +msgstr "" + +#: ../../en/rasters.rst:93 +msgid "If you are using Postgres.App, you'll find raster2pgsql among the other `Postgres.app CLI Tools `_." +msgstr "" + +#: ../../en/rasters.rst:95 +msgid "On Ubuntu and Debian, you will need" +msgstr "" + +#: ../../en/rasters.rst:101 +msgid "to have the PostGIS commandline tools installed. This may install an additional version of PostgreSQL as well. You can see a list of clusters in Debian/Ubuntu using the :command:`pg_lsclusters` command and drop them using the :command:`pg_dropcluster` command." +msgstr "" + +#: ../../en/rasters.rst:106 +msgid "For this and later exercises, we'll be using `nyc_dem.tif` found in the file `PG Raster Workshop Dataset https://postgis.net/stuff/workshop-data/postgis_raster_workshop.zip `_. For some geometry/raster examples, we will also be using NYC data loaded from prior chapters. In-lieu of loading the tif, you can restore the `nyc_dem.backup` included in the zip file in your database using the :command:`pg_restore` commandline tool or the pgAdmin **Restore** menu." +msgstr "" + +#: ../../en/rasters.rst:112 +msgid "This raster data was sourced from `NYC DEM 1-foot Integer `_ which is a 3GB DEM tif representing elevation relative to sea level with buildings and overwater removed. We then created a lower res version of it." +msgstr "" + +#: ../../en/rasters.rst:115 +msgid "The :command:`rasterpgsql` tool is similar to the :command:`shp2gpsql` except instead of loading ESRI shapefiles into PostGIS geometry/geography tables, it loads any GDAL supported raster format into raster tables. Just like :command:`shp2pgsql` you can pass it a spatial reference id (SRID) of the source. Unlike :command:`shp2pgsql` it can infer the spatial references system of the source data if your source data has suitable metadata." +msgstr "" + +#: ../../en/rasters.rst:119 +msgid "For a full exposure of all the possible switches offered refer to `raster2pgsql options `_." +msgstr "" + +#: ../../en/rasters.rst:121 +msgid "Some other notable options :command:`raster2pgsql` offers which we will not cover are:" +msgstr "" + +#: ../../en/rasters.rst:123 +msgid "Ability to denote the SRID of the source. Instead, we'll rely on raster2pgsql guessing skills." +msgstr "" + +#: ../../en/rasters.rst:124 +msgid "Ability to set the `nodata` value, when not specified, raster2pgsql tries to infer from the file." +msgstr "" + +#: ../../en/rasters.rst:125 +msgid "Abiliity to load out-of-database rasters." +msgstr "" + +#: ../../en/rasters.rst:127 +msgid "To load all the tif files in our folder and also create overviews, we would run the below." +msgstr "" + +#: ../../en/rasters.rst:133 +msgid "-d to drop the tables if they already exist" +msgstr "" + +#: ../../en/rasters.rst:134 +msgid "The above command uses `-e` to do load immediately instead of committing in a transaction" +msgstr "" + +#: ../../en/rasters.rst:135 +msgid "`-C` set raster constraints, this is useful for `raster_columns` to show info. You may want to combine with `-x` to exclude the extent constraint, which is a slow constraint to check and also hampers future loads in the table." +msgstr "" + +#: ../../en/rasters.rst:138 +msgid "`-M` to vacuum and analyze after load, to improve query planner statistics" +msgstr "" + +#: ../../en/rasters.rst:139 +msgid "`-Y` to use copy in batches of 50. If you are running PostGIS 3.3 or higher, you can use `-Y 1000` to have copy be in batches of 1000, or even higher number. This will run faster, but will use more memory." +msgstr "" + +#: ../../en/rasters.rst:141 +msgid "`-l 2,3` to create over view tables: `o_2_ncy_dem` and `o_3_nyc_dem`. This is useful for viewing data." +msgstr "" + +#: ../../en/rasters.rst:142 +msgid "-I to create a spatial index" +msgstr "" + +#: ../../en/rasters.rst:143 +msgid "`-F` to add file name, if you have only one tif file, this is kinda pointless. If you had multiple, this would be useful to tell you what file each row came from." +msgstr "" + +#: ../../en/rasters.rst:145 +msgid "`-t` to set the block size. Note if you are not sure the best size use, use `-t auto` instead and raster2pgql will use the same tiling as what was in the tif. The output will tell you what the blocksize is it chose. Cancel if it looks huge or weird. The original file had a size of 300x7 which is not ideal." +msgstr "" + +#: ../../en/rasters.rst:149 +msgid "Use :command:`psql` to run the generated sql against the database. If you want to dump to a file instead, use `> nyc_dem.sql`" +msgstr "" + +#: ../../en/rasters.rst:153 +msgid "For this example, we have only one tif file, so we could instead specify the full file name, instead of `*.tif`. If the files are not in your current directory, you can also specify a folder path with `*.tif`." +msgstr "" + +#: ../../en/rasters.rst:158 +msgid "If you are on windows and need to reference the folder, make sure to include the drive letter such as `C:/workshop/*.tif`" +msgstr "" + +#: ../../en/rasters.rst:161 +msgid "You'll often hear in PostGIS lingo, the term **raster tile** and **raster** used somewhat interchangeably. A raster tile really corresponds to a particular raster in a raster column which is a subset of a bigger raster, such as this NYC dem data we just loaded. This is because when rasters are loaded into PostGIS from big raster files, they chopped into many rows to make them manageable. Each raster in each row then is a part of a bigger raster. Each tile covers same size area denoted by the blocksize you specified. Rasters are sadly limited by the 1GB PostgreSQL `TOAST `_ limit and also the slow process of detoasting and so we need to chop up in order to achieve decent performance or to even store them." +msgstr "" + +#: ../../en/rasters.rst:170 msgid "Viewing Rasters in Browser" msgstr "" -#: ../../en/rasters.rst:86 -msgid "Although pgAdmin and psql have no mechanism yet to view postgis rasters, we have a couple of options. For smallish rasters the easiest is to output to a web-friendly raster format such as PNG using batteries included postgis raster functions like `ST_AsPNG` or `ST_AsGDALRaster` listed in `PostGIS Raster output functions `_. As your rasters get larger, you'll want to graduate to a tool such as QGIS to view them in all their glory or the GDAL family of commandline tools such as gdal_translate to export them to other raster formats. Remember though, postgis rasters are built for analysis, not for generating pretty pictures for you to look at." +#: ../../en/rasters.rst:171 +msgid "Although pgAdmin and psql have no mechanism yet to view postgis rasters, we have a couple of options. For smallish rasters the easiest is to output to a web-friendly raster format such as PNG using batteries included postgis raster functions like `ST_AsPNG` or `ST_AsGDALRaster` listed in `PostGIS Raster output functions `_. As your rasters get larger, you'll want to graduate to a tool such as QGIS to view them in all their glory or the GDAL family of commandline tools such as :command:`gdal_translate` to export them to other raster formats. Remember though, postgis rasters are built for analysis, not for generating pretty pictures for you to look at." msgstr "" -#: ../../en/rasters.rst:93 +#: ../../en/rasters.rst:178 msgid "One caveat, by default all different raster types outputs are disabled. In order to utilize these, you'll need to enable drivers, all or a subset as detailed in `Enable GDAL Raster drivers `_" msgstr "" -#: ../../en/rasters.rst:101 +#: ../../en/rasters.rst:186 msgid "If you don't want to have to do this for each connection, you can set at the database level using:" msgstr "" -#: ../../en/rasters.rst:107 +#: ../../en/rasters.rst:192 msgid "Each new connection to the database will use that setting." msgstr "" -#: ../../en/rasters.rst:109 +#: ../../en/rasters.rst:194 msgid "Run the below query and copy and paste the output into the address bar of your web browser." msgstr "" -#: ../../en/rasters.rst:120 +#: ../../en/rasters.rst:205 msgid "For the rasters created thus far, we didn't specify the number of bands nor did we even define their relation to earth. As such our rasters have an unknown spatial reference system (0)." msgstr "" -#: ../../en/rasters.rst:123 +#: ../../en/rasters.rst:208 msgid "You can think of a rasters exoskeletal as a geometry. A matrix encased in a geometric envelop. In order to do useful analysis, we need to georeference our rasters, meaning we want each pixel (rectangle) to represent some meaningful plot of space." msgstr "" -#: ../../en/rasters.rst:128 +#: ../../en/rasters.rst:213 msgid "The `ST_AsRaster` has many overloaded representations. The earlier example used the simplest such implementation and accepted the default arguments which are 8BUI and 1 band, with no data being 0. If you need to use the other variants, you should use the named arguments call syntax so that you don't accidentally fall into the wrong variant of the function or get **function is not unique** errors." msgstr "" -#: ../../en/rasters.rst:133 -msgid "If you start with a geometry that has a spatial reference system, you'll end up with a raster with same spatial reference system. In this next example, we'll plop our words in New York in bright cheery colors. We will also use pixel scale instead of width and height so that our raster pixel sizes represent 1 meter x 1 meter of space." +#: ../../en/rasters.rst:221 +msgid "If you start with a geometry that has a spatial reference system, you'll end up with a raster with same spatial reference system. In this next example, we'll plop our words in New York in bright cheery colors. We will also use pixel scale instead of width and height so that our raster pixel sizes represent 1 meter x 1 meter of space." msgstr "" -#: ../../en/rasters.rst:155 +#: ../../en/rasters.rst:244 msgid "If we then look at this, we'll see a non-squashed colored geometry." msgstr "" -#: ../../en/rasters.rst:166 +#: ../../en/rasters.rst:255 msgid "Repeat for Raster:" msgstr "" -#: ../../en/rasters.rst:177 +#: ../../en/rasters.rst:266 msgid "What is more telling, if we rerun the" msgstr "" -#: ../../en/rasters.rst:184 +#: ../../en/rasters.rst:273 msgid "Observe the metadata of the New York entries. They have the New York state plane meter spatial reference system. They also have the same scale. Since each unit is 1x1 meter, the width of the word **Raster** is now wider than **Hello**." msgstr "" -#: ../../en/rasters.rst:199 +#: ../../en/rasters.rst:288 msgid "Raster Spatial Catalog tables" msgstr "" -#: ../../en/rasters.rst:200 -msgid "Similar to the geometry and geography types, raster has a set of catalogs that show you all raster columns in your database. These are `raster_columns and raster_overviews `_. Both of these are views similar to the `geometry_columns` and `geography_columns`." +#: ../../en/rasters.rst:289 +msgid "Similar to the geometry and geography types, raster has a set of catalogs that show you all raster columns in your database. These are `raster_columns and raster_overviews `_." msgstr "" -#: ../../en/rasters.rst:210 +#: ../../en/rasters.rst:295 +msgid "raster_columns" +msgstr "" + +#: ../../en/rasters.rst:297 +msgid "The `raster_columns` view to the sibling to the `geometry_columns` and `geography_columns`, providing much the same data and more, but for raster columns." +msgstr "" + +#: ../../en/rasters.rst:305 msgid "Explore the table, and you'll find this:" msgstr "" -#: ../../en/rasters.rst:219 -msgid "a very disappointing row of largely unfilled information." +#: ../../en/rasters.rst:317 +msgid "a disappointing row of largely unfilled information for the `rasters` table." msgstr "" -#: ../../en/rasters.rst:221 +#: ../../en/rasters.rst:319 msgid "Unlike geometry and geography, raster does not support type modifiers, because type modifier space is too limited and there are more critical properties than what can fit in a type modifier." msgstr "" -#: ../../en/rasters.rst:224 -msgid "Raster instead relies on constraints, and reads these constraints back as part of the view. So let's try to add some constraints to our table." +#: ../../en/rasters.rst:322 +msgid "Raster instead relies on constraints, and reads these constraints back as part of the view." +msgstr "" + +#: ../../en/rasters.rst:324 +msgid "Look at the other rows from the tables we loaded using :command:`raster2pgsql`. Because we used the `-C` switch :command:`raster2pgsql` added constraints for the srid and other info it was able to read from the tif or that we passed in. The overview tables generated with the `-l` switch `o_2_nyc_dem` and `o_3_nyc_dem` show up as well." msgstr "" -#: ../../en/rasters.rst:232 -msgid "And you'll be bombarded with a whole bunch of notices about how your raster data is mess and nothing can be constrained. If you look at raster_columns again, still the same disappointing story of many blank rows." +#: ../../en/rasters.rst:327 +msgid "Let's try to add some constraints to our table." msgstr "" -#: ../../en/rasters.rst:236 +#: ../../en/rasters.rst:334 +msgid "And you'll be bombarded with a whole bunch of notices about how your raster data is a mess and nothing can be constrained. If you look at raster_columns again, still the same disappointing story of many blank rows for `rasters`." +msgstr "" + +#: ../../en/rasters.rst:338 msgid "In order for constraints to be applied, all rasters in your table must be constrainable by at least one rule." msgstr "" -#: ../../en/rasters.rst:239 +#: ../../en/rasters.rst:341 msgid "We can perhaps do this, let's just lie and say all our data is in New York State plane." msgstr "" -#: ../../en/rasters.rst:252 +#: ../../en/rasters.rst:355 msgid "Ah progress:" msgstr "" -#: ../../en/rasters.rst:261 +#: ../../en/rasters.rst:364 msgid "The more you can constrain all your rasters, the more columns you'll see filled in and also the more operations you'll be able to do across all the tiles in your raster. Keep in mind that in some cases, you may not want to apply all constraints." msgstr "" -#: ../../en/rasters.rst:265 +#: ../../en/rasters.rst:368 msgid "For example, if you plan to load more data into your raster table, you'll want to skip the extent constraint since that would require that all rasters are within the extent of the extent constraint." msgstr "" -#: ../../en/rasters.rst:269 -msgid "You'll often here in PostGIS lingo, the term **raster tile** and **raster** used somewhat interchangeably. A raster tile really corresponds to a particular raster in a raster column which is a subset of a bigger raster. This is because when rasters are loaded into PostGIS from big raster files, they are often chopped up to make them manageable." +#: ../../en/rasters.rst:373 +msgid "raster_overviews" +msgstr "" + +#: ../../en/rasters.rst:374 +msgid "Raster overview columns appear both in the `raster_columns` meta catalog and another meta catalog called `raster_overviews`. Overviews are used mostly to speed up viewing at higher zoom levels. They can also be used for quick back of the envelop analysis, providing less accurate stats, but at a much faster speed than applying to the raw raster table." +msgstr "" + +#: ../../en/rasters.rst:379 +msgid "To inspect the overviews, run:" msgstr "" -#: ../../en/rasters.rst:275 -msgid "Exploring Raster Functions" +#: ../../en/rasters.rst:386 +msgid "and you'll see the output:" msgstr "" -#: ../../en/rasters.rst:276 -msgid "The :command:`postgis_raster` extension has over 100 functions to choose from. We'll focus on the ones you will commonly use. PostGIS raster functionality was patterned after the PostGIS geometry support. As such you'll find an overlap of functions between raster and geometry where it makes sense. Common ones you'll use that have equivalent in geometry world are :command:`ST_Intersects`, :command:`ST_SetSRID`, :command:`ST_SRID`, :command:`ST_Union`, :command:`ST_Intersection`, and :command:`ST_Transform`. In addition to those overlapping functions, it offers many functions that work in conjunction with geometry or are very specific to rasters." +#: ../../en/rasters.rst:396 +msgid "The `raster_overviews` table only provides you the overview_factor and the name of the parent table. All this information is something you could have figured out yourself by the `raster2pgsql` naming convention for overviews." msgstr "" -#: ../../en/rasters.rst:285 -msgid "Unioning Rasters" +#: ../../en/rasters.rst:400 +msgid "The `overview_factor` tells you at what resolution the row is with respect to it's parent. An `overview_factor` of `2` means that 2x2 = 4 tiles can fit into one overview_2 tile. Similarly an overview_factor of `1` meants that 2x2x2 = 8 tiles of the original can be shoved into an overview_3 tile." msgstr "" -#: ../../en/rasters.rst:286 +#: ../../en/rasters.rst:407 +msgid "Common Raster Functions" +msgstr "" + +#: ../../en/rasters.rst:408 +msgid "The :command:`postgis_raster` extension has over 100 functions to choose from. PostGIS raster functionality was patterned after the PostGIS geometry support. You'll find an overlap of functions between raster and geometry where it makes sense. Common ones you'll use that have equivalent in geometry world are :command:`ST_Intersects`, :command:`ST_SetSRID`, :command:`ST_SRID`, :command:`ST_Union`, :command:`ST_Intersection`, and :command:`ST_Transform`." +msgstr "" + +#: ../../en/rasters.rst:415 +msgid "In addition to those overlapping functions, it supports the `&&` overlap operator between rasters and between a raster and geometry. It also offers many functions that work in conjunction with geometry or are very specific to rasters." +msgstr "" + +#: ../../en/rasters.rst:419 +msgid "You need a function like :command:`ST_Union` to reconstitute a region. Because performance gets slow, the more pixels a function needs to analyse, you need a fast acting function :command:`ST_Clip` to clip the rasters to just the portions of interest for your analysis." +msgstr "" + +#: ../../en/rasters.rst:423 +msgid "Finally you need :command:`ST_Intersects` or :command:`&&` to zoom in on the raster tiles that contain your areas of interest. The `&&` operator, is a faster process than the `ST_Intersects`. Both can take advantage of raster spatial indexes. We'll cover these bread and butter functions first before moving on to other sections where we will use them in concert with other raster and geometry functions." +msgstr "" + +#: ../../en/rasters.rst:429 +msgid "Unioning Rasters with ST_Union" +msgstr "" + +#: ../../en/rasters.rst:430 msgid "The `ST_Union `_ function for raster, just as the geometry equivalent :command:`ST_Union`, aggregates a set of rasters together into a single raster. However, just as with geometry, not all rasters can be combined together, but the rules for raster unioning are more complicated than geometry rules. In the case of geometries, all you need is to have the same spatial reference system, but for rasters that is not sufficient." msgstr "" -#: ../../en/rasters.rst:294 -msgid "If you were to attempt, the following" +#: ../../en/rasters.rst:438 +msgid "If you were to attempt, the following:" msgstr "" -#: ../../en/rasters.rst:301 +#: ../../en/rasters.rst:445 msgid "You'd be summarily punished with an error:" msgstr "" -#: ../../en/rasters.rst:303 +#: ../../en/rasters.rst:447 msgid "**ERROR: rt_raster_from_two_rasters: The two rasters provided do not have the same alignment SQL state: XX000**" msgstr "" -#: ../../en/rasters.rst:306 +#: ../../en/rasters.rst:450 msgid "What is this same alignment thing, that is preventing you from unioning your precious rasters?" msgstr "" -#: ../../en/rasters.rst:308 +#: ../../en/rasters.rst:452 msgid "In order for rasters to be combined, they need to be on the same grid so to speak. Meaning they must have same pixel sizes, same orientation (the skew), same spatial reference system, and their pixels must not cut into each other, meaning they share the same worldly pixel grid." msgstr "" -#: ../../en/rasters.rst:312 +#: ../../en/rasters.rst:456 msgid "If you try the same query, but just with words we carefully placed in New York." msgstr "" -#: ../../en/rasters.rst:314 +#: ../../en/rasters.rst:458 msgid "Again, the same error. These are the same spatial ref system, the same pixel sizes, and yet it's still not good enough. Because their grids are off." msgstr "" -#: ../../en/rasters.rst:318 +#: ../../en/rasters.rst:462 msgid "We can fix this by shifting the upper left y coordinates ever so slightly and then trying again. If our grids start at integer level since our pixel sizes are whole integer, then the pixels won't cut into each other." msgstr "" -#: ../../en/rasters.rst:333 ../../en/rasters.rst:382 +#: ../../en/rasters.rst:477 ../../en/rasters.rst:526 msgid "Voila it worked, and if we were to view, we'd see something like this:" msgstr "" -#: ../../en/rasters.rst:339 +#: ../../en/rasters.rst:483 msgid "If ever you are unclear why your rasters don't have the same alignment, you can use the function `ST_SameAlignment `_, which will compare 2 rasters or a set of rasters and tell you if they have the same alignment. If you have notices enabled, the NOTICE will tell you what is off with the rasters in question. The `ST_NotSameAlignmentReason `_, instead of just a notice will output the reason. It however only works with two rasters at a time." msgstr "" -#: ../../en/rasters.rst:346 +#: ../../en/rasters.rst:490 msgid "One major way in which the `ST_Union(raster) `_ raster function deviates from the `ST_Union(geometry) `_ geometry function is that it allows for an argument called *uniontype*. This argument by default is set to `LAST` if you don't specify it, which means, take the **LAST** raster pixel values in occasions where the raster pixel values overlap. As a general rule, pixels in a band that are marked as no-data are ignored." msgstr "" -#: ../../en/rasters.rst:352 +#: ../../en/rasters.rst:496 msgid "Just as with most aggregates in PostgreSQL, you can put a :command:`ORDER BY` clause as part of the function call as is done in the prior example. Specifying the order, allows you to control which raster takes priority. So in our prior example, *Raster* trumped *Hello* because *Raster* is alphabetically last." msgstr "" -#: ../../en/rasters.rst:356 +#: ../../en/rasters.rst:500 msgid "Observe, if you switch the order:" msgstr "" -#: ../../en/rasters.rst:366 +#: ../../en/rasters.rst:510 msgid "Then *Hello* trumps *Raster* because Hello is now the last overlaid." msgstr "" -#: ../../en/rasters.rst:368 +#: ../../en/rasters.rst:512 msgid "The :command:`FIRST` union type is the reverse of :command:`LAST`." msgstr "" -#: ../../en/rasters.rst:370 +#: ../../en/rasters.rst:514 msgid "But on occassion, **LAST** may not be the right operation. Let's suppose our rasters represented two different sets of observations from two different devices. These devices measure the same thing, and we aren't sure which is right when they cross paths, so we'd instead like to take the `MEAN` of the results. We'd do this:" msgstr "" -#: ../../en/rasters.rst:386 +#: ../../en/rasters.rst:530 msgid "So instead of trumping, we have a blending of the two forces. In the case of :command:`MEAN` union type, there is no point in specifying order, because the result would be the average of overlapping pixel values." msgstr "" -#: ../../en/rasters.rst:390 +#: ../../en/rasters.rst:534 msgid "Note that for geometries since geometries are vector and thus have no values besides there or not there, there really isn't any ambiguity on how to combine two vectors when they intersect." msgstr "" -#: ../../en/rasters.rst:394 +#: ../../en/rasters.rst:538 msgid "Another feature of the raster :command:`ST_Union` we glossed over, is this idea of if you should return all bands or just some bands. When you don't specify what bands to union, :command:`ST_Union` will combine same banded numbers and use the :command:`LAST` unioning strategy. If you have multiple bands, this may not be what you want to do. Perhaps you only want to union, the second band. In this case, the Green Band and you want the count of pixel values." msgstr "" -#: ../../en/rasters.rst:415 +#: ../../en/rasters.rst:559 msgid "Note in the case of the **COUNT** union type, which counts the number of pixels filled in and returns that value, the result is always a **32BUI** similar to how when you do a :command:`COUNT` in sql, the result is always a bigint, to accommodate large counts." msgstr "" -#: ../../en/rasters.rst:419 +#: ../../en/rasters.rst:563 msgid "In other cases, the band pixel type does not change and is set to the max value or rounded if the amounts exceed the bounds of the type. Why would anyone ever want to count pixels that intersect at a location. Well suppose each of your rasters represent police squadrons and incidents of arrests in the areas. Each value, might represent a different kind of arrest reason. You are doing stats on how many arrests in each region, therefore you only care about the count of arrests." msgstr "" -#: ../../en/rasters.rst:428 +#: ../../en/rasters.rst:572 msgid "Or perhaps, you want to do all bands, but you want different strategies." msgstr "" -#: ../../en/rasters.rst:438 +#: ../../en/rasters.rst:582 msgid "Using the *unionarg[]* variant of the :command:`ST_Union` function, also allows you to shuffle the order of the bands." msgstr "" -#: ../../en/rasters.rst:441 -msgid "Clipping Rasters" +#: ../../en/rasters.rst:585 +msgid "Clipping Rasters with help of ST_Intersects" msgstr "" -#: ../../en/rasters.rst:442 +#: ../../en/rasters.rst:586 msgid "The `ST_Clip `_ function is one of the most widely used functions for PostGIS rasters. The main reason is the more pixels you need to inspect or do operations on, the slower your processing. **ST_Clip** clips your raster to just the area of interest, so you can isolate your operations to just that area." msgstr "" -#: ../../en/rasters.rst:446 +#: ../../en/rasters.rst:590 msgid "This function is also special in that it utilizes the power of geometry to help raster analysis. To reduce the number of pixels, :command:`ST_Union` has to handle, each raster is clipped first to the area we are interested in." msgstr "" -#: ../../en/rasters.rst:458 -msgid "This example showcases several functions working in unison. The :command:`ST_Intersects` function employed is the one packaged with **postgis_raster** and can intersect 2 rasters or a raster and a geometry. Similar to the geometry :command:`ST_Intersects` the raster :command:`ST_Intersects` can take advantage of spatial indexes on the raster or geometry tables." +#: ../../en/rasters.rst:602 +msgid "This example showcases several functions working in unison. The :command:`ST_Intersects` function employed is the one packaged with **postgis_raster** and can intersect 2 rasters or a raster and a geometry. Similar to the geometry :command:`ST_Intersects` the `raster ST_Intersects `_ can take advantage of spatial indexes on the raster or geometry tables." msgstr "" -#: ../../en/rasters.rst:464 +#: ../../en/rasters.rst:609 msgid "Converting Rasters to Geometries" msgstr "" -#: ../../en/rasters.rst:465 -msgid "Rasters can just as easily be morphed into geometries. Lets start with our prior example, but convert it to a polygon using `ST_Polygon `_ function." +#: ../../en/rasters.rst:610 +msgid "Rasters can just as easily be morphed into geometries." +msgstr "" + +#: ../../en/rasters.rst:613 +msgid "The polygon of a raster with ST_Polygon" +msgstr "" + +#: ../../en/rasters.rst:614 +msgid "Lets start with our prior example, but convert it to a polygon using `ST_Polygon `_ function." msgstr "" -#: ../../en/rasters.rst:477 +#: ../../en/rasters.rst:625 msgid "If you click on the geometry viewer in pgAdmin, you can see this in all it's glory without any hacks." msgstr "" -#: ../../en/rasters.rst:481 -msgid "ST_Polygon considers all the pixels that have values (not no-data) in a particular band, and converts them to geometry. Like many other functions in raster, ST_Polygon only considers 1 band. If no band is specified, it will consider only the first band." +#: ../../en/rasters.rst:629 +msgid ":command:`ST_Polygon` considers all the pixels that have values (not no-data) in a particular band, and converts them to geometry. Like many other functions in raster, :command:`ST_Polygon` only considers 1 band. If no band is specified, it will consider only the first band." +msgstr "" + +#: ../../en/rasters.rst:634 +msgid "The pixel rectangles of a raster with ST_PixelAsPolygons" msgstr "" -#: ../../en/rasters.rst:485 +#: ../../en/rasters.rst:635 msgid "Another popularly used function is the `ST_PixelAsPolygons `_ function. You should rarely use :command:`ST_PixelAsPolygons` on a large raster without first clipping because you will end up with millions of rows, one for each pixel." msgstr "" -#: ../../en/rasters.rst:488 +#: ../../en/rasters.rst:638 msgid ":command:`ST_PixelAsPolygons` returns a table consisting of geom, val, x, and y. Where x is the column number, and y is the row number in the raster." msgstr "" -#: ../../en/rasters.rst:491 +#: ../../en/rasters.rst:641 msgid ":command:`ST_PixelAsPolygons` similar to other raster functions works on one band at a time and works on band 1 if no band is specified. It also by default returns only pixels that have values." msgstr "" -#: ../../en/rasters.rst:503 +#: ../../en/rasters.rst:653 msgid "Which outputs:" msgstr "" -#: ../../en/rasters.rst:507 +#: ../../en/rasters.rst:657 msgid "and if we inspect using the geometry viewer, we'd see:" msgstr "" -#: ../../en/rasters.rst:511 +#: ../../en/rasters.rst:661 msgid "If we want all pixels of all our bands, we'd need to do something like below. Note the differences in this example from previous." msgstr "" -#: ../../en/rasters.rst:514 +#: ../../en/rasters.rst:664 msgid "1. Setting :command:`exclude_nodata_value` to make sure all pixels are returned so that our sets of calls return the same number of rows. The rows out of the function will be naturally in the same order." msgstr "" -#: ../../en/rasters.rst:517 +#: ../../en/rasters.rst:667 msgid "2. Using the `PostgreSQL ROWS FROM constructor `_ , and aliasing each set of columns from our function output with names. So for example the band 1 columns (geom, val, x, y) are renamed to g1, v1, x1, x2" msgstr "" -#: ../../en/rasters.rst:538 +#: ../../en/rasters.rst:688 msgid "We used CROSS JOIN LATERAL in these examples because we wanted to be explicit what we are doing. Since these are all set returning functions, you can replace CROSS JOIN LATERAL with , for short-hand. We'll use a , in the next set of examples" msgstr "" -#: ../../en/rasters.rst:543 +#: ../../en/rasters.rst:694 +msgid "Dumping polygons with ST_DumpAsPolygons" +msgstr "" + +#: ../../en/rasters.rst:696 msgid "Raster also introduces an additional composite type called a :command:`geomval`. Consider a :command:`geomval` as the offspring of a geometry and raster. It contains a geometry and it contains a pixel value." msgstr "" -#: ../../en/rasters.rst:547 +#: ../../en/rasters.rst:700 msgid "You will find several raster functions that return geomvals." msgstr "" -#: ../../en/rasters.rst:549 +#: ../../en/rasters.rst:702 msgid "A commonly used function that outputs geomvals is `ST_DumpAsPolygons `_, which returns a set of contiguous pixels with the same value as a polygon. Again this by default will only check band 1 and exclude no data values unless you override. This example selects only polygons from band 2. You can also apply filters to the values. For most use cases, :command:`ST_DumpAsPolygons` is a better option than :command:`ST_PixelAsPolygons` as it will return far fewer rows." msgstr "" -#: ../../en/rasters.rst:554 +#: ../../en/rasters.rst:707 msgid "This will output 6 rows, and return polygons corresponding to the letters in \"Raster\"." msgstr "" -#: ../../en/rasters.rst:565 +#: ../../en/rasters.rst:718 msgid "Note that it doesn't return a single geometry, because it finds continguous set of pixels with the same value that form a polygon. Even though all these values are the same, they are not continguous." msgstr "" -#: ../../en/rasters.rst:571 +#: ../../en/rasters.rst:724 msgid "A common approach to produce more complex geometries is to group by the values and union." msgstr "" -#: ../../en/rasters.rst:581 +#: ../../en/rasters.rst:734 msgid "This will give you 2 rows back corresponding to the words \"Raster\" and \"Hello\"." msgstr "" -#: ../../en/rasters.rst:585 +#: ../../en/rasters.rst:737 +msgid "Statistics" +msgstr "" + +#: ../../en/rasters.rst:738 +msgid "The most important thing to understand about rasters is that they are statistical tools for storing data in arrays, that you may happen to be able to make look pretty on a screen." +msgstr "" + +#: ../../en/rasters.rst:741 +msgid "You can find a menu of these statistical functions in `Raster Band Statistics `_." +msgstr "" + +#: ../../en/rasters.rst:745 +msgid "ST_SummaryStatsAgg and ST_SummaryStats" +msgstr "" + +#: ../../en/rasters.rst:747 +msgid "Want all stats for a set or rasters, reach for the function `ST_SummaryStatsAgg `_." +msgstr "" + +#: ../../en/rasters.rst:749 +msgid "This query takes about 10 seconds and gives you a summary of the whole table:" +msgstr "" + +#: ../../en/rasters.rst:756 +msgid "Outputs:" +msgstr "" + +#: ../../en/rasters.rst:765 +msgid "Which tells we have a lot of pixels and our max elevation is 411 ft." +msgstr "" + +#: ../../en/rasters.rst:767 +msgid "If you have built overviews, and just need a rough estimate of your mins, maxs, and means use one of your overviews. This next query returns roughly the same values for mins, maxs, and means as the prior but in about 1 second instead of 10." +msgstr "" + +#: ../../en/rasters.rst:776 +msgid "Now armed with this bit of information, we can ask more questions." +msgstr "" + +#: ../../en/rasters.rst:779 +msgid "ST_Histogram" +msgstr "" + +#: ../../en/rasters.rst:781 +msgid "Generally you won't want stats for your whole table, but instead just stats for a particular area, in that case, you'll want to also employ our old friends :command:`ST_Intersects` and :command:`ST_Clip`. If you are also in need of a raster statistics function that doesn't have an aggregate version, you'll want to carry :command:`ST_Union` along for the ride." +msgstr "" + +#: ../../en/rasters.rst:786 +msgid "For this next example we'll use a different stats function `ST_Histogram `_ which has no aggregate equivalent, and for this particular variant, is a set returning function. We are using the same area of interest as some prior examples, but we also need to employ geometry :command:`ST_Transform` to transform our NY state plane meters geometry to our NYC State Plane feet rasters. It is almost always more performant to transform the geometry instead of raster and definitely if your geometry is just a single one." +msgstr "" + +#: ../../en/rasters.rst:803 +msgid "the above query completes in under 60ms and outputs:" +msgstr "" + +#: ../../en/rasters.rst:817 +msgid "Creating Derivative Rasters" +msgstr "" + +#: ../../en/rasters.rst:818 +msgid "PostGIS raster comes packaged with a number of functions for editing rasters. These functions are both used for editing as well as creating derivative raster data sets. You will find these listed in `Raster Editors `_ and `Raster Management `_." +msgstr "" + +#: ../../en/rasters.rst:824 +msgid "Transforming rasters with ST_Transform" +msgstr "" + +#: ../../en/rasters.rst:825 +msgid "Most of our data is in NY State Plane meters (SRID: 26918), however our DEM raster dataset is in NY State Plane feet (SRID: 2263). For the least cumbersome workflow, we need our core datasets to be in the same spatial reference system." +msgstr "" + +#: ../../en/rasters.rst:829 +msgid "The `raster ST_Transform `_ is the function most suited for this job." +msgstr "" + +#: ../../en/rasters.rst:831 +msgid "In order to create a new nyc dem dataset in NY State Plane meters, we'll do the following:" +msgstr "" + +#: ../../en/rasters.rst:841 +msgid "The above on my system took about 1.5 minutes. For a larger data set it would take much longer." +msgstr "" + +#: ../../en/rasters.rst:844 +msgid "The aforementioned examples used two variants of the :command:`ST_Transform` raster function. The first was to get a reference raster that will be used to transform the other raster tiles to guarantee that all tiles have the same alignment. Note the second variant of :command:`ST_Transform` used doesn't even take an input SRID. This is because the SRID and all the pixel scale and block sizes are read from the reference raster. If you used `ST_Transform(rast, srid)` form, then all your rasters might come out with different alignment making it impossible to apply an operation such as :command:`ST_Union` on them." +msgstr "" + +#: ../../en/rasters.rst:851 +msgid "The only problem with the aforementioned :command:`ST_Transform` approach is that when you transform, the transformed often exists in other tiles. If you looked at the above output closely enough by outputting the convex hull of the rasters, in the next example" +msgstr "" + +#: ../../en/rasters.rst:855 +msgid "you'd see annoying overlaps around the borders." +msgstr "" + +#: ../../en/rasters.rst:864 +msgid "viewed in pgAdmin would look something like:" +msgstr "" + +#: ../../en/rasters.rst:870 +msgid "Using ST_MakeEmptyCoverage to create even tiled rasters" +msgstr "" + +#: ../../en/rasters.rst:871 +msgid "A better approach, albeit a bit slower, is to define your own coverage tile structure from scratch using `ST_MakeEmptyCoverage `_ and then find the intersecting tiles for each new tile, and ST_Union these and then use `ST_Transform(ref, ST_Union...)` to create each tile." +msgstr "" + +#: ../../en/rasters.rst:875 +msgid "For this we'll be using quite a few functions, we learned about earlier." +msgstr "" + +#: ../../en/rasters.rst:900 +msgid "Repeating the same exercise as earlier:" +msgstr "" + +#: ../../en/rasters.rst:909 +msgid "viewed in pgAdmin we no longer have overlaps:" +msgstr "" + +#: ../../en/rasters.rst:913 +msgid "On my system this took ~10 minutes and returned 3879 rows. After the creation of the table, we'll want to do the usual of adding a spatial index, primary key, and constraints as follows:" +msgstr "" + +#: ../../en/rasters.rst:928 +msgid "Which should take under 2 minutes for this dataset." +msgstr "" + +#: ../../en/rasters.rst:931 +msgid "Creating overview tables with ST_CreateOverview" +msgstr "" + +#: ../../en/rasters.rst:933 +msgid "Just as with our original dataset, it would be useful to have overview tables to speed up performance of some operations. `ST_CreateOverview `_ is a function fit for that purpose. You can use :command:`ST_CreateOverview` to create overviews also if you neglected to create one during the raster2pgsql load or you decided, you need more overviews." +msgstr "" + +#: ../../en/rasters.rst:939 +msgid "We'll create level 2 and 3 overviews as we had done with our original using this code." +msgstr "" + +#: ../../en/rasters.rst:946 +msgid "This process sadly takes a while, and a longer while the more rows you have so be patient. For this dataset it took about 3-5 minutes for the overview factor `2` and 1 minute for the overview factor `3`." +msgstr "" + +#: ../../en/rasters.rst:949 +msgid "The :command:`ST_CreateOverView` function also adds in the needed constraints so the columns appear with full detail in the `raster_columns` and `raster_overviews` catalogs. It does not add indexes to them though and also does not add an rid column. The rid column is probably not necessary unless you need a primary key to edit with. You would probably want an index which you can create with the following:" +msgstr "" + +#: ../../en/rasters.rst:964 +msgid "ST_CreateOverview has an optional argument for denoting the sampling method. If not specified it uses the default `NearestNeighbor` which is generally the fastest to compute but may not be ideal. Resampling methods is beyond the scope of this workshop." +msgstr "" + +#: ../../en/rasters.rst:970 +msgid "The intersection of rasters and geometries" +msgstr "" + +#: ../../en/rasters.rst:971 +msgid "There are a couple of functions commonly used to compute intersections of rasters and geometries. We've already seen :command:`ST_Clip` in action which returns the intersection of a raster and geometry as a raster, but there are others. For point data, the most commonly used is :command:`ST_Value` and then there is the :command:`ST_Intersection` which has several overloads some returning rasters and some returning a set of `geomval`." +msgstr "" + +#: ../../en/rasters.rst:979 +msgid "Pixel values at a geometric Point" +msgstr "" + +#: ../../en/rasters.rst:981 +msgid "If you need to return values from rasters based on intersection of several ad-hoc geometry points, you'll use `ST_Value `_ or it's nearest relative `ST_NearestValue `_." +msgstr "" + +#: ../../en/rasters.rst:995 +msgid "This example takes about 1 second to return 2444 rows. If you used :command:`ST_Intersects` instead of :command:`&&`, the process would take about 3 seconds. The reason `ST_Intersects` is slower is that it performs an additional recheck in some cases a pixel by pixel check. If you expect all your points to be represented with data in your raster set and your rasters represent a coverage (a continguous set non-overlapping raster tiles), then `&&` is generally a speedier option." +msgstr "" + +#: ../../en/rasters.rst:1000 +msgid "If your raster data is not densely populated or you have overlapping rasters (e.g. they represent different observations in time), or they are skewed (not axis aligned) then there is an advantage to having ST_Intersects weed out the false positives." +msgstr "" + +#: ../../en/rasters.rst:1006 +msgid "ST_Intersection raster style" +msgstr "" + +#: ../../en/rasters.rst:1007 +msgid "Just as you can compute the intersection of two geometries using :command:`ST_Intersection`, you can compute intersection of two rasters or a raster and a geometry using `raster ST_Intersection `_." +msgstr "" + +#: ../../en/rasters.rst:1011 +msgid "What you get out of this beast, are two different kinds of things:" +msgstr "" + +#: ../../en/rasters.rst:1013 +msgid "Intersect a geometry with a raster, and you get a set of `geomval` offspring. Perhaps one, but most often many." +msgstr "" + +#: ../../en/rasters.rst:1016 +msgid "Intersect 2 rasters and you get a single `raster` back." +msgstr "" + +#: ../../en/rasters.rst:1018 +msgid "The golden rule for both raster intersection and geometry intersection is that both parties involved must have the same spatial reference system. For raster/raster, they also have to have same alignment." +msgstr "" + +#: ../../en/rasters.rst:1022 +msgid "Here is an example which answers a question you may have been curious about. If we bucket our elevations into 5 buckets of elevation values, which elevation range results in the most gun fatalities? We know based on our earlier summary statistics that `0` is the lowest value and `411` is the highest value for elevation in our nyc dem dataset, so we use that as min and max value for our `width_bucket `_ call." +msgstr "" + +#: ../../en/rasters.rst:1044 +msgid "Is there an important correlation between gun homicides and elevation? Probably not." +msgstr "" + +#: ../../en/rasters.rst:1048 +msgid "Let's take a look at raster / raster intersection:" +msgstr "" + +#: ../../en/rasters.rst:1057 +msgid "What we get are two rows with NULLLs, and if you have your PostgreSQL set to show notices, you'll see:" +msgstr "" + +#: ../../en/rasters.rst:1059 +msgid "**NOTICE: The two rasters provided do not have the same alignment. Returning NULL**" +msgstr "" + +#: ../../en/rasters.rst:1061 +msgid "In order to fix this, we can align one to the other as it's coming out of the gate using `ST_Resample `_." +msgstr "" + +#: ../../en/rasters.rst:1071 +msgid "Let's also roll it up into a single stats record" +msgstr "" + +#: ../../en/rasters.rst:1083 +msgid "which outputs:" +msgstr "" + +#: ../../en/rasters.rst:1094 msgid "Map Algebra Functions" msgstr "" -#: ../../en/rasters.rst:586 -msgid "Map algebra is the idea that you can do math on your pixel values. The :command:`ST_Union` function covered earlier is a special fast case of map algebra. Then there are the `ST_MapAlgebra `_ family of functions which allow you to define your own crazy math, but at cost of performance." +#: ../../en/rasters.rst:1095 +msgid "Map algebra is the idea that you can do math on your pixel values. The :command:`ST_Union` and :command:`ST_Intersection` functions covered earlier are a special fast case of map algebra. Then there are the `ST_MapAlgebra `_ family of functions which allow you to define your own crazy math, but at cost of performance." msgstr "" -#: ../../en/rasters.rst:592 +#: ../../en/rasters.rst:1103 msgid "People have the habit of jumping to :command:`ST_MapAlgebra`, probably cause the name sounds so cool and sophisticated. Who wouldn't want to tell their friends, \"I'm using a function called ST_MapAlgebra.\" My advice, explore other functions before you jump for that shot-gun. Your life will be simpler and your performance will be 100 times better, and your code will be shorter." msgstr "" -#: ../../en/rasters.rst:598 +#: ../../en/rasters.rst:1109 +msgid "Before we showcase `ST_MapAlgebra`, we'll explore other functions that fit under the `Map Algebra` family of functions and generally have better performance than `ST_MapAlgebra`." +msgstr "" + +#: ../../en/rasters.rst:1113 +msgid "Reclassify your raster using ST_Reclass" +msgstr "" + +#: ../../en/rasters.rst:1115 msgid "An often overlooked map-algebraish function is the `ST_Reclass `_ function, who sits in the background waiting for someone to discover the power and speed it can offer." msgstr "" -#: ../../en/rasters.rst:602 +#: ../../en/rasters.rst:1119 msgid "What does **ST_Reclass** do? It as the name implies, reclassifies your pixel values based on minimalist range algebra." msgstr "" + +#: ../../en/rasters.rst:1121 +msgid "Lets revisit our NYC Dems. Perhaps we only care about classifying our elevations as 1) low, 2) medium, 3) high , and 4) really high. We don't need 411 values, we just need 4. With that said lets do some reclassifying." +msgstr "" + +#: ../../en/rasters.rst:1124 +msgid "The classification scheme is governed by the `reclass expression `_." +msgstr "" + +#: ../../en/rasters.rst:1140 +msgid "Which would output:" +msgstr "" + +#: ../../en/rasters.rst:1152 +msgid "If this were a classification scheme we preferred, we could create a new table using the ST_Reclass to recompute each tile." +msgstr "" + +#: ../../en/rasters.rst:1155 +msgid "Coloring your rasters with ST_ColorMap" +msgstr "" + +#: ../../en/rasters.rst:1156 +msgid "The `ST_ColorMap `_ function is another mapalgebraish function that reclassifies your pixel values. Except it is band creating. It converts a single band raster such as our Dems into a visually presentable 3 or 4 banded raster." +msgstr "" + +#: ../../en/rasters.rst:1160 +msgid "You could use one of the built-in colormaps as below if you don't want to fuss with creating one." +msgstr "" + +#: ../../en/rasters.rst:1171 +msgid "Which looks like:" +msgstr "" + +#: ../../en/rasters.rst:1175 +msgid "The bluer the color the lower the elevation and the redder the color the higher the elevation." +msgstr "" diff --git a/postgis-intro/sources/locale/es/LC_MESSAGES/rasters.po b/postgis-intro/sources/locale/es/LC_MESSAGES/rasters.po index 376b773e..17cd270b 100644 --- a/postgis-intro/sources/locale/es/LC_MESSAGES/rasters.po +++ b/postgis-intro/sources/locale/es/LC_MESSAGES/rasters.po @@ -9,7 +9,7 @@ msgid "" msgstr "" "Project-Id-Version: Introduction to PostGIS 1.1\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2023-01-13 00:30-0500\n" +"POT-Creation-Date: 2023-01-25 04:15-0500\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" @@ -31,378 +31,826 @@ msgstr "" msgid "Although pretty pictures such as those you see on your TV screen are rasters, rasters may not be that exciting to look at. In a nutshell, a raster is a matrix, pinned on a coordinate system, that has values that can represent anything you want them to represent." msgstr "" -#: ../../en/rasters.rst:15 -msgid "Since rasters live in cartesian space, rasters can interact with geometries. PostGIS offers many functions that take as input both rasters and geometries. Also many operations applied to rasters will result in geometries. Common ones are the `ST_Polygon`, `ST_Envelope`, `ST_ConvexHull`, and `ST_MinConvexHull` as shown below." +#: ../../en/rasters.rst:17 +msgid "Since rasters live in cartesian space, rasters can interact with geometries. PostGIS offers many functions that take as input both rasters and geometries. Many operations applied to rasters will result in geometries. Common ones are the `ST_Polygon`, `ST_Envelope`, `ST_ConvexHull`, and `ST_MinConvexHull` as shown below. When you cast a raster to a geometry, what is output is the `ST_ConvexHull` of the raster." msgstr "" -#: ../../en/rasters.rst:21 -msgid "The raster format is commonly used to store elevation data, temperature data, satellite data, and thematic data representing things like environmental contamination, population density, and environmental hazard occurrences." +#: ../../en/rasters.rst:24 +msgid "The raster format is commonly used to store elevation data, temperature data, satellite data, and thematic data representing things like environmental contamination, population density, and environmental hazard occurrences. You can use rasters to store any numeric data that has a meaningful coordinate location. The only restriction is that for all data in a specific band the numeric data types have to be the same." msgstr "" -#: ../../en/rasters.rst:23 -msgid "Although raster data can be created from scratch in PostGIS, a more common approach is to load raster data from various formats using the `raster2pgsql `_ command line tool packaged with PostGIS. Before all of that, you must enable raster support in your database by running the command:" +#: ../../en/rasters.rst:28 +msgid "Although raster data can be created from scratch in PostGIS, a more common approach is to load raster data from various formats using the :command:`raster2pgsql` command line tool packaged with PostGIS. Before all of that, you must enable raster support in your database by running the command:" msgstr "" -#: ../../en/rasters.rst:30 +#: ../../en/rasters.rst:37 msgid "Creating Rasters From Geometries" msgstr "" -#: ../../en/rasters.rst:31 +#: ../../en/rasters.rst:38 msgid "We'll start off by first creating raster data from vector data, and then move on to the more exciting approach of loading data from a raster source. You will find that raster data is available in abundance and often free from various government sites." msgstr "" -#: ../../en/rasters.rst:34 +#: ../../en/rasters.rst:41 msgid "We'll start by converting some geometries into rasters using `ST_AsRaster `_ function as follows." msgstr "" -#: ../../en/rasters.rst:48 -msgid "The above example CREATEs a table (**rasters**) from geometries formed from letters using the PostGIS 3.2+ `ST_Letters `_ function. Rasters similar to geometries, can take advantage of spatial indexes. The spatial index used for raster is a functional index that indexes the geometry convexhull of the raster. When loading data with :command:`raster2pgsql` with the :command:`I` switch, the :command:`CREATE INDEX` step is done for you." +#: ../../en/rasters.rst:55 +msgid "The above example CREATEs a table (**rasters**) from geometries formed from letters using the PostGIS 3.2+ `ST_Letters `_ function. Rasters similar to geometries, can take advantage of spatial indexes. The spatial index used for raster is a functional index that indexes the geometry convexhull of the raster." msgstr "" -#: ../../en/rasters.rst:53 -msgid "You can see some useful metadata of your rasters with the following query which utilizes the postgis raster functions `ST_Count `_ function to count the number of pixels that have data and the `ST_MetaData `_ function to provide all sorts of useful background info for our rasters." +#: ../../en/rasters.rst:58 +msgid "You can see some useful metadata of your rasters with the following query which utilizes the postgis raster `ST_Count `_ function to count the number of pixels that have data and the `ST_MetaData `_ function to provide all sorts of useful background info for our rasters." msgstr "" -#: ../../en/rasters.rst:71 -msgid "There are two levels of raster functions. There are functions such as ST_MetaData that work at the raster level and there are functions such as :command:`ST_Count` function and :command:`ST_BandMetaData `_ function that work at the band level. Most functions in postgis raster that work at the band level, work with only one band at a time, and assume the band you want is `1`." +#: ../../en/rasters.rst:76 +msgid "There are two levels of raster functions. There are functions such as ST_MetaData that work at the raster level and there are functions such as :command:`ST_Count` function and `ST_BandMetaData `_ function that work at the band level. Most functions in postgis raster that work at the band level, work with only one band at a time, and assume the band you want is `1`." msgstr "" -#: ../../en/rasters.rst:78 +#: ../../en/rasters.rst:83 +msgid "If you have a multi-band raster, and you need to count the pixel not no-data values in a band other than 1, you would explicitly specify the band number as follows `ST_Count(rast,2)`." +msgstr "" + +#: ../../en/rasters.rst:85 msgid "Note how all the rasters have a 150x150 dimension. This is not ideal. This means that in order to force that, our rasters, are squished in all sorts of ways. If only we could see the ugliness of the rasters before us." msgstr "" -#: ../../en/rasters.rst:81 -msgid "If you have a multi-band raster, and you need to count the pixel not no-data values in a band other than 1, you would explicitly specify the band number as follows `ST_Count(rast,2)`." +#: ../../en/rasters.rst:89 +msgid "Loading Rasters using raster2pgsql" msgstr "" -#: ../../en/rasters.rst:85 +#: ../../en/rasters.rst:90 +msgid "`raster2pgsql `_ is a command-line tool often packaged with PostGIS. If you are on windows and used application stackbuilder PostGIS Bundle, you'll find :command:`raster2pgsql.exe` in the folder ``C:\\Program Files\\PostgreSQL\\15\\bin`` where the *15* should be replaced with the version of PostgreSQL you are running." +msgstr "" + +#: ../../en/rasters.rst:93 +msgid "If you are using Postgres.App, you'll find raster2pgsql among the other `Postgres.app CLI Tools `_." +msgstr "" + +#: ../../en/rasters.rst:95 +msgid "On Ubuntu and Debian, you will need" +msgstr "" + +#: ../../en/rasters.rst:101 +msgid "to have the PostGIS commandline tools installed. This may install an additional version of PostgreSQL as well. You can see a list of clusters in Debian/Ubuntu using the :command:`pg_lsclusters` command and drop them using the :command:`pg_dropcluster` command." +msgstr "" + +#: ../../en/rasters.rst:106 +msgid "For this and later exercises, we'll be using `nyc_dem.tif` found in the file `PG Raster Workshop Dataset https://postgis.net/stuff/workshop-data/postgis_raster_workshop.zip `_. For some geometry/raster examples, we will also be using NYC data loaded from prior chapters. In-lieu of loading the tif, you can restore the `nyc_dem.backup` included in the zip file in your database using the :command:`pg_restore` commandline tool or the pgAdmin **Restore** menu." +msgstr "" + +#: ../../en/rasters.rst:112 +msgid "This raster data was sourced from `NYC DEM 1-foot Integer `_ which is a 3GB DEM tif representing elevation relative to sea level with buildings and overwater removed. We then created a lower res version of it." +msgstr "" + +#: ../../en/rasters.rst:115 +msgid "The :command:`rasterpgsql` tool is similar to the :command:`shp2gpsql` except instead of loading ESRI shapefiles into PostGIS geometry/geography tables, it loads any GDAL supported raster format into raster tables. Just like :command:`shp2pgsql` you can pass it a spatial reference id (SRID) of the source. Unlike :command:`shp2pgsql` it can infer the spatial references system of the source data if your source data has suitable metadata." +msgstr "" + +#: ../../en/rasters.rst:119 +msgid "For a full exposure of all the possible switches offered refer to `raster2pgsql options `_." +msgstr "" + +#: ../../en/rasters.rst:121 +msgid "Some other notable options :command:`raster2pgsql` offers which we will not cover are:" +msgstr "" + +#: ../../en/rasters.rst:123 +msgid "Ability to denote the SRID of the source. Instead, we'll rely on raster2pgsql guessing skills." +msgstr "" + +#: ../../en/rasters.rst:124 +msgid "Ability to set the `nodata` value, when not specified, raster2pgsql tries to infer from the file." +msgstr "" + +#: ../../en/rasters.rst:125 +msgid "Abiliity to load out-of-database rasters." +msgstr "" + +#: ../../en/rasters.rst:127 +msgid "To load all the tif files in our folder and also create overviews, we would run the below." +msgstr "" + +#: ../../en/rasters.rst:133 +msgid "-d to drop the tables if they already exist" +msgstr "" + +#: ../../en/rasters.rst:134 +msgid "The above command uses `-e` to do load immediately instead of committing in a transaction" +msgstr "" + +#: ../../en/rasters.rst:135 +msgid "`-C` set raster constraints, this is useful for `raster_columns` to show info. You may want to combine with `-x` to exclude the extent constraint, which is a slow constraint to check and also hampers future loads in the table." +msgstr "" + +#: ../../en/rasters.rst:138 +msgid "`-M` to vacuum and analyze after load, to improve query planner statistics" +msgstr "" + +#: ../../en/rasters.rst:139 +msgid "`-Y` to use copy in batches of 50. If you are running PostGIS 3.3 or higher, you can use `-Y 1000` to have copy be in batches of 1000, or even higher number. This will run faster, but will use more memory." +msgstr "" + +#: ../../en/rasters.rst:141 +msgid "`-l 2,3` to create over view tables: `o_2_ncy_dem` and `o_3_nyc_dem`. This is useful for viewing data." +msgstr "" + +#: ../../en/rasters.rst:142 +msgid "-I to create a spatial index" +msgstr "" + +#: ../../en/rasters.rst:143 +msgid "`-F` to add file name, if you have only one tif file, this is kinda pointless. If you had multiple, this would be useful to tell you what file each row came from." +msgstr "" + +#: ../../en/rasters.rst:145 +msgid "`-t` to set the block size. Note if you are not sure the best size use, use `-t auto` instead and raster2pgql will use the same tiling as what was in the tif. The output will tell you what the blocksize is it chose. Cancel if it looks huge or weird. The original file had a size of 300x7 which is not ideal." +msgstr "" + +#: ../../en/rasters.rst:149 +msgid "Use :command:`psql` to run the generated sql against the database. If you want to dump to a file instead, use `> nyc_dem.sql`" +msgstr "" + +#: ../../en/rasters.rst:153 +msgid "For this example, we have only one tif file, so we could instead specify the full file name, instead of `*.tif`. If the files are not in your current directory, you can also specify a folder path with `*.tif`." +msgstr "" + +#: ../../en/rasters.rst:158 +msgid "If you are on windows and need to reference the folder, make sure to include the drive letter such as `C:/workshop/*.tif`" +msgstr "" + +#: ../../en/rasters.rst:161 +msgid "You'll often hear in PostGIS lingo, the term **raster tile** and **raster** used somewhat interchangeably. A raster tile really corresponds to a particular raster in a raster column which is a subset of a bigger raster, such as this NYC dem data we just loaded. This is because when rasters are loaded into PostGIS from big raster files, they chopped into many rows to make them manageable. Each raster in each row then is a part of a bigger raster. Each tile covers same size area denoted by the blocksize you specified. Rasters are sadly limited by the 1GB PostgreSQL `TOAST `_ limit and also the slow process of detoasting and so we need to chop up in order to achieve decent performance or to even store them." +msgstr "" + +#: ../../en/rasters.rst:170 msgid "Viewing Rasters in Browser" msgstr "" -#: ../../en/rasters.rst:86 -msgid "Although pgAdmin and psql have no mechanism yet to view postgis rasters, we have a couple of options. For smallish rasters the easiest is to output to a web-friendly raster format such as PNG using batteries included postgis raster functions like `ST_AsPNG` or `ST_AsGDALRaster` listed in `PostGIS Raster output functions `_. As your rasters get larger, you'll want to graduate to a tool such as QGIS to view them in all their glory or the GDAL family of commandline tools such as gdal_translate to export them to other raster formats. Remember though, postgis rasters are built for analysis, not for generating pretty pictures for you to look at." +#: ../../en/rasters.rst:171 +msgid "Although pgAdmin and psql have no mechanism yet to view postgis rasters, we have a couple of options. For smallish rasters the easiest is to output to a web-friendly raster format such as PNG using batteries included postgis raster functions like `ST_AsPNG` or `ST_AsGDALRaster` listed in `PostGIS Raster output functions `_. As your rasters get larger, you'll want to graduate to a tool such as QGIS to view them in all their glory or the GDAL family of commandline tools such as :command:`gdal_translate` to export them to other raster formats. Remember though, postgis rasters are built for analysis, not for generating pretty pictures for you to look at." msgstr "" -#: ../../en/rasters.rst:93 +#: ../../en/rasters.rst:178 msgid "One caveat, by default all different raster types outputs are disabled. In order to utilize these, you'll need to enable drivers, all or a subset as detailed in `Enable GDAL Raster drivers `_" msgstr "" -#: ../../en/rasters.rst:101 +#: ../../en/rasters.rst:186 msgid "If you don't want to have to do this for each connection, you can set at the database level using:" msgstr "" -#: ../../en/rasters.rst:107 +#: ../../en/rasters.rst:192 msgid "Each new connection to the database will use that setting." msgstr "" -#: ../../en/rasters.rst:109 +#: ../../en/rasters.rst:194 msgid "Run the below query and copy and paste the output into the address bar of your web browser." msgstr "" -#: ../../en/rasters.rst:120 +#: ../../en/rasters.rst:205 msgid "For the rasters created thus far, we didn't specify the number of bands nor did we even define their relation to earth. As such our rasters have an unknown spatial reference system (0)." msgstr "" -#: ../../en/rasters.rst:123 +#: ../../en/rasters.rst:208 msgid "You can think of a rasters exoskeletal as a geometry. A matrix encased in a geometric envelop. In order to do useful analysis, we need to georeference our rasters, meaning we want each pixel (rectangle) to represent some meaningful plot of space." msgstr "" -#: ../../en/rasters.rst:128 +#: ../../en/rasters.rst:213 msgid "The `ST_AsRaster` has many overloaded representations. The earlier example used the simplest such implementation and accepted the default arguments which are 8BUI and 1 band, with no data being 0. If you need to use the other variants, you should use the named arguments call syntax so that you don't accidentally fall into the wrong variant of the function or get **function is not unique** errors." msgstr "" -#: ../../en/rasters.rst:133 -msgid "If you start with a geometry that has a spatial reference system, you'll end up with a raster with same spatial reference system. In this next example, we'll plop our words in New York in bright cheery colors. We will also use pixel scale instead of width and height so that our raster pixel sizes represent 1 meter x 1 meter of space." +#: ../../en/rasters.rst:221 +msgid "If you start with a geometry that has a spatial reference system, you'll end up with a raster with same spatial reference system. In this next example, we'll plop our words in New York in bright cheery colors. We will also use pixel scale instead of width and height so that our raster pixel sizes represent 1 meter x 1 meter of space." msgstr "" -#: ../../en/rasters.rst:155 +#: ../../en/rasters.rst:244 msgid "If we then look at this, we'll see a non-squashed colored geometry." msgstr "" -#: ../../en/rasters.rst:166 +#: ../../en/rasters.rst:255 msgid "Repeat for Raster:" msgstr "" -#: ../../en/rasters.rst:177 +#: ../../en/rasters.rst:266 msgid "What is more telling, if we rerun the" msgstr "" -#: ../../en/rasters.rst:184 +#: ../../en/rasters.rst:273 msgid "Observe the metadata of the New York entries. They have the New York state plane meter spatial reference system. They also have the same scale. Since each unit is 1x1 meter, the width of the word **Raster** is now wider than **Hello**." msgstr "" -#: ../../en/rasters.rst:199 +#: ../../en/rasters.rst:288 msgid "Raster Spatial Catalog tables" msgstr "" -#: ../../en/rasters.rst:200 -msgid "Similar to the geometry and geography types, raster has a set of catalogs that show you all raster columns in your database. These are `raster_columns and raster_overviews `_. Both of these are views similar to the `geometry_columns` and `geography_columns`." +#: ../../en/rasters.rst:289 +msgid "Similar to the geometry and geography types, raster has a set of catalogs that show you all raster columns in your database. These are `raster_columns and raster_overviews `_." msgstr "" -#: ../../en/rasters.rst:210 +#: ../../en/rasters.rst:295 +msgid "raster_columns" +msgstr "" + +#: ../../en/rasters.rst:297 +msgid "The `raster_columns` view to the sibling to the `geometry_columns` and `geography_columns`, providing much the same data and more, but for raster columns." +msgstr "" + +#: ../../en/rasters.rst:305 msgid "Explore the table, and you'll find this:" msgstr "" -#: ../../en/rasters.rst:219 -msgid "a very disappointing row of largely unfilled information." +#: ../../en/rasters.rst:317 +msgid "a disappointing row of largely unfilled information for the `rasters` table." msgstr "" -#: ../../en/rasters.rst:221 +#: ../../en/rasters.rst:319 msgid "Unlike geometry and geography, raster does not support type modifiers, because type modifier space is too limited and there are more critical properties than what can fit in a type modifier." msgstr "" -#: ../../en/rasters.rst:224 -msgid "Raster instead relies on constraints, and reads these constraints back as part of the view. So let's try to add some constraints to our table." +#: ../../en/rasters.rst:322 +msgid "Raster instead relies on constraints, and reads these constraints back as part of the view." +msgstr "" + +#: ../../en/rasters.rst:324 +msgid "Look at the other rows from the tables we loaded using :command:`raster2pgsql`. Because we used the `-C` switch :command:`raster2pgsql` added constraints for the srid and other info it was able to read from the tif or that we passed in. The overview tables generated with the `-l` switch `o_2_nyc_dem` and `o_3_nyc_dem` show up as well." msgstr "" -#: ../../en/rasters.rst:232 -msgid "And you'll be bombarded with a whole bunch of notices about how your raster data is mess and nothing can be constrained. If you look at raster_columns again, still the same disappointing story of many blank rows." +#: ../../en/rasters.rst:327 +msgid "Let's try to add some constraints to our table." msgstr "" -#: ../../en/rasters.rst:236 +#: ../../en/rasters.rst:334 +msgid "And you'll be bombarded with a whole bunch of notices about how your raster data is a mess and nothing can be constrained. If you look at raster_columns again, still the same disappointing story of many blank rows for `rasters`." +msgstr "" + +#: ../../en/rasters.rst:338 msgid "In order for constraints to be applied, all rasters in your table must be constrainable by at least one rule." msgstr "" -#: ../../en/rasters.rst:239 +#: ../../en/rasters.rst:341 msgid "We can perhaps do this, let's just lie and say all our data is in New York State plane." msgstr "" -#: ../../en/rasters.rst:252 +#: ../../en/rasters.rst:355 msgid "Ah progress:" msgstr "" -#: ../../en/rasters.rst:261 +#: ../../en/rasters.rst:364 msgid "The more you can constrain all your rasters, the more columns you'll see filled in and also the more operations you'll be able to do across all the tiles in your raster. Keep in mind that in some cases, you may not want to apply all constraints." msgstr "" -#: ../../en/rasters.rst:265 +#: ../../en/rasters.rst:368 msgid "For example, if you plan to load more data into your raster table, you'll want to skip the extent constraint since that would require that all rasters are within the extent of the extent constraint." msgstr "" -#: ../../en/rasters.rst:269 -msgid "You'll often here in PostGIS lingo, the term **raster tile** and **raster** used somewhat interchangeably. A raster tile really corresponds to a particular raster in a raster column which is a subset of a bigger raster. This is because when rasters are loaded into PostGIS from big raster files, they are often chopped up to make them manageable." +#: ../../en/rasters.rst:373 +msgid "raster_overviews" +msgstr "" + +#: ../../en/rasters.rst:374 +msgid "Raster overview columns appear both in the `raster_columns` meta catalog and another meta catalog called `raster_overviews`. Overviews are used mostly to speed up viewing at higher zoom levels. They can also be used for quick back of the envelop analysis, providing less accurate stats, but at a much faster speed than applying to the raw raster table." +msgstr "" + +#: ../../en/rasters.rst:379 +msgid "To inspect the overviews, run:" msgstr "" -#: ../../en/rasters.rst:275 -msgid "Exploring Raster Functions" +#: ../../en/rasters.rst:386 +msgid "and you'll see the output:" msgstr "" -#: ../../en/rasters.rst:276 -msgid "The :command:`postgis_raster` extension has over 100 functions to choose from. We'll focus on the ones you will commonly use. PostGIS raster functionality was patterned after the PostGIS geometry support. As such you'll find an overlap of functions between raster and geometry where it makes sense. Common ones you'll use that have equivalent in geometry world are :command:`ST_Intersects`, :command:`ST_SetSRID`, :command:`ST_SRID`, :command:`ST_Union`, :command:`ST_Intersection`, and :command:`ST_Transform`. In addition to those overlapping functions, it offers many functions that work in conjunction with geometry or are very specific to rasters." +#: ../../en/rasters.rst:396 +msgid "The `raster_overviews` table only provides you the overview_factor and the name of the parent table. All this information is something you could have figured out yourself by the `raster2pgsql` naming convention for overviews." msgstr "" -#: ../../en/rasters.rst:285 -msgid "Unioning Rasters" +#: ../../en/rasters.rst:400 +msgid "The `overview_factor` tells you at what resolution the row is with respect to it's parent. An `overview_factor` of `2` means that 2x2 = 4 tiles can fit into one overview_2 tile. Similarly an overview_factor of `1` meants that 2x2x2 = 8 tiles of the original can be shoved into an overview_3 tile." msgstr "" -#: ../../en/rasters.rst:286 +#: ../../en/rasters.rst:407 +msgid "Common Raster Functions" +msgstr "" + +#: ../../en/rasters.rst:408 +msgid "The :command:`postgis_raster` extension has over 100 functions to choose from. PostGIS raster functionality was patterned after the PostGIS geometry support. You'll find an overlap of functions between raster and geometry where it makes sense. Common ones you'll use that have equivalent in geometry world are :command:`ST_Intersects`, :command:`ST_SetSRID`, :command:`ST_SRID`, :command:`ST_Union`, :command:`ST_Intersection`, and :command:`ST_Transform`." +msgstr "" + +#: ../../en/rasters.rst:415 +msgid "In addition to those overlapping functions, it supports the `&&` overlap operator between rasters and between a raster and geometry. It also offers many functions that work in conjunction with geometry or are very specific to rasters." +msgstr "" + +#: ../../en/rasters.rst:419 +msgid "You need a function like :command:`ST_Union` to reconstitute a region. Because performance gets slow, the more pixels a function needs to analyse, you need a fast acting function :command:`ST_Clip` to clip the rasters to just the portions of interest for your analysis." +msgstr "" + +#: ../../en/rasters.rst:423 +msgid "Finally you need :command:`ST_Intersects` or :command:`&&` to zoom in on the raster tiles that contain your areas of interest. The `&&` operator, is a faster process than the `ST_Intersects`. Both can take advantage of raster spatial indexes. We'll cover these bread and butter functions first before moving on to other sections where we will use them in concert with other raster and geometry functions." +msgstr "" + +#: ../../en/rasters.rst:429 +msgid "Unioning Rasters with ST_Union" +msgstr "" + +#: ../../en/rasters.rst:430 msgid "The `ST_Union `_ function for raster, just as the geometry equivalent :command:`ST_Union`, aggregates a set of rasters together into a single raster. However, just as with geometry, not all rasters can be combined together, but the rules for raster unioning are more complicated than geometry rules. In the case of geometries, all you need is to have the same spatial reference system, but for rasters that is not sufficient." msgstr "" -#: ../../en/rasters.rst:294 -msgid "If you were to attempt, the following" +#: ../../en/rasters.rst:438 +msgid "If you were to attempt, the following:" msgstr "" -#: ../../en/rasters.rst:301 +#: ../../en/rasters.rst:445 msgid "You'd be summarily punished with an error:" msgstr "" -#: ../../en/rasters.rst:303 +#: ../../en/rasters.rst:447 msgid "**ERROR: rt_raster_from_two_rasters: The two rasters provided do not have the same alignment SQL state: XX000**" msgstr "" -#: ../../en/rasters.rst:306 +#: ../../en/rasters.rst:450 msgid "What is this same alignment thing, that is preventing you from unioning your precious rasters?" msgstr "" -#: ../../en/rasters.rst:308 +#: ../../en/rasters.rst:452 msgid "In order for rasters to be combined, they need to be on the same grid so to speak. Meaning they must have same pixel sizes, same orientation (the skew), same spatial reference system, and their pixels must not cut into each other, meaning they share the same worldly pixel grid." msgstr "" -#: ../../en/rasters.rst:312 +#: ../../en/rasters.rst:456 msgid "If you try the same query, but just with words we carefully placed in New York." msgstr "" -#: ../../en/rasters.rst:314 +#: ../../en/rasters.rst:458 msgid "Again, the same error. These are the same spatial ref system, the same pixel sizes, and yet it's still not good enough. Because their grids are off." msgstr "" -#: ../../en/rasters.rst:318 +#: ../../en/rasters.rst:462 msgid "We can fix this by shifting the upper left y coordinates ever so slightly and then trying again. If our grids start at integer level since our pixel sizes are whole integer, then the pixels won't cut into each other." msgstr "" -#: ../../en/rasters.rst:333 ../../en/rasters.rst:382 +#: ../../en/rasters.rst:477 ../../en/rasters.rst:526 msgid "Voila it worked, and if we were to view, we'd see something like this:" msgstr "" -#: ../../en/rasters.rst:339 +#: ../../en/rasters.rst:483 msgid "If ever you are unclear why your rasters don't have the same alignment, you can use the function `ST_SameAlignment `_, which will compare 2 rasters or a set of rasters and tell you if they have the same alignment. If you have notices enabled, the NOTICE will tell you what is off with the rasters in question. The `ST_NotSameAlignmentReason `_, instead of just a notice will output the reason. It however only works with two rasters at a time." msgstr "" -#: ../../en/rasters.rst:346 +#: ../../en/rasters.rst:490 msgid "One major way in which the `ST_Union(raster) `_ raster function deviates from the `ST_Union(geometry) `_ geometry function is that it allows for an argument called *uniontype*. This argument by default is set to `LAST` if you don't specify it, which means, take the **LAST** raster pixel values in occasions where the raster pixel values overlap. As a general rule, pixels in a band that are marked as no-data are ignored." msgstr "" -#: ../../en/rasters.rst:352 +#: ../../en/rasters.rst:496 msgid "Just as with most aggregates in PostgreSQL, you can put a :command:`ORDER BY` clause as part of the function call as is done in the prior example. Specifying the order, allows you to control which raster takes priority. So in our prior example, *Raster* trumped *Hello* because *Raster* is alphabetically last." msgstr "" -#: ../../en/rasters.rst:356 +#: ../../en/rasters.rst:500 msgid "Observe, if you switch the order:" msgstr "" -#: ../../en/rasters.rst:366 +#: ../../en/rasters.rst:510 msgid "Then *Hello* trumps *Raster* because Hello is now the last overlaid." msgstr "" -#: ../../en/rasters.rst:368 +#: ../../en/rasters.rst:512 msgid "The :command:`FIRST` union type is the reverse of :command:`LAST`." msgstr "" -#: ../../en/rasters.rst:370 +#: ../../en/rasters.rst:514 msgid "But on occassion, **LAST** may not be the right operation. Let's suppose our rasters represented two different sets of observations from two different devices. These devices measure the same thing, and we aren't sure which is right when they cross paths, so we'd instead like to take the `MEAN` of the results. We'd do this:" msgstr "" -#: ../../en/rasters.rst:386 +#: ../../en/rasters.rst:530 msgid "So instead of trumping, we have a blending of the two forces. In the case of :command:`MEAN` union type, there is no point in specifying order, because the result would be the average of overlapping pixel values." msgstr "" -#: ../../en/rasters.rst:390 +#: ../../en/rasters.rst:534 msgid "Note that for geometries since geometries are vector and thus have no values besides there or not there, there really isn't any ambiguity on how to combine two vectors when they intersect." msgstr "" -#: ../../en/rasters.rst:394 +#: ../../en/rasters.rst:538 msgid "Another feature of the raster :command:`ST_Union` we glossed over, is this idea of if you should return all bands or just some bands. When you don't specify what bands to union, :command:`ST_Union` will combine same banded numbers and use the :command:`LAST` unioning strategy. If you have multiple bands, this may not be what you want to do. Perhaps you only want to union, the second band. In this case, the Green Band and you want the count of pixel values." msgstr "" -#: ../../en/rasters.rst:415 +#: ../../en/rasters.rst:559 msgid "Note in the case of the **COUNT** union type, which counts the number of pixels filled in and returns that value, the result is always a **32BUI** similar to how when you do a :command:`COUNT` in sql, the result is always a bigint, to accommodate large counts." msgstr "" -#: ../../en/rasters.rst:419 +#: ../../en/rasters.rst:563 msgid "In other cases, the band pixel type does not change and is set to the max value or rounded if the amounts exceed the bounds of the type. Why would anyone ever want to count pixels that intersect at a location. Well suppose each of your rasters represent police squadrons and incidents of arrests in the areas. Each value, might represent a different kind of arrest reason. You are doing stats on how many arrests in each region, therefore you only care about the count of arrests." msgstr "" -#: ../../en/rasters.rst:428 +#: ../../en/rasters.rst:572 msgid "Or perhaps, you want to do all bands, but you want different strategies." msgstr "" -#: ../../en/rasters.rst:438 +#: ../../en/rasters.rst:582 msgid "Using the *unionarg[]* variant of the :command:`ST_Union` function, also allows you to shuffle the order of the bands." msgstr "" -#: ../../en/rasters.rst:441 -msgid "Clipping Rasters" +#: ../../en/rasters.rst:585 +msgid "Clipping Rasters with help of ST_Intersects" msgstr "" -#: ../../en/rasters.rst:442 +#: ../../en/rasters.rst:586 msgid "The `ST_Clip `_ function is one of the most widely used functions for PostGIS rasters. The main reason is the more pixels you need to inspect or do operations on, the slower your processing. **ST_Clip** clips your raster to just the area of interest, so you can isolate your operations to just that area." msgstr "" -#: ../../en/rasters.rst:446 +#: ../../en/rasters.rst:590 msgid "This function is also special in that it utilizes the power of geometry to help raster analysis. To reduce the number of pixels, :command:`ST_Union` has to handle, each raster is clipped first to the area we are interested in." msgstr "" -#: ../../en/rasters.rst:458 -msgid "This example showcases several functions working in unison. The :command:`ST_Intersects` function employed is the one packaged with **postgis_raster** and can intersect 2 rasters or a raster and a geometry. Similar to the geometry :command:`ST_Intersects` the raster :command:`ST_Intersects` can take advantage of spatial indexes on the raster or geometry tables." +#: ../../en/rasters.rst:602 +msgid "This example showcases several functions working in unison. The :command:`ST_Intersects` function employed is the one packaged with **postgis_raster** and can intersect 2 rasters or a raster and a geometry. Similar to the geometry :command:`ST_Intersects` the `raster ST_Intersects `_ can take advantage of spatial indexes on the raster or geometry tables." msgstr "" -#: ../../en/rasters.rst:464 +#: ../../en/rasters.rst:609 msgid "Converting Rasters to Geometries" msgstr "" -#: ../../en/rasters.rst:465 -msgid "Rasters can just as easily be morphed into geometries. Lets start with our prior example, but convert it to a polygon using `ST_Polygon `_ function." +#: ../../en/rasters.rst:610 +msgid "Rasters can just as easily be morphed into geometries." +msgstr "" + +#: ../../en/rasters.rst:613 +msgid "The polygon of a raster with ST_Polygon" +msgstr "" + +#: ../../en/rasters.rst:614 +msgid "Lets start with our prior example, but convert it to a polygon using `ST_Polygon `_ function." msgstr "" -#: ../../en/rasters.rst:477 +#: ../../en/rasters.rst:625 msgid "If you click on the geometry viewer in pgAdmin, you can see this in all it's glory without any hacks." msgstr "" -#: ../../en/rasters.rst:481 -msgid "ST_Polygon considers all the pixels that have values (not no-data) in a particular band, and converts them to geometry. Like many other functions in raster, ST_Polygon only considers 1 band. If no band is specified, it will consider only the first band." +#: ../../en/rasters.rst:629 +msgid ":command:`ST_Polygon` considers all the pixels that have values (not no-data) in a particular band, and converts them to geometry. Like many other functions in raster, :command:`ST_Polygon` only considers 1 band. If no band is specified, it will consider only the first band." +msgstr "" + +#: ../../en/rasters.rst:634 +msgid "The pixel rectangles of a raster with ST_PixelAsPolygons" msgstr "" -#: ../../en/rasters.rst:485 +#: ../../en/rasters.rst:635 msgid "Another popularly used function is the `ST_PixelAsPolygons `_ function. You should rarely use :command:`ST_PixelAsPolygons` on a large raster without first clipping because you will end up with millions of rows, one for each pixel." msgstr "" -#: ../../en/rasters.rst:488 +#: ../../en/rasters.rst:638 msgid ":command:`ST_PixelAsPolygons` returns a table consisting of geom, val, x, and y. Where x is the column number, and y is the row number in the raster." msgstr "" -#: ../../en/rasters.rst:491 +#: ../../en/rasters.rst:641 msgid ":command:`ST_PixelAsPolygons` similar to other raster functions works on one band at a time and works on band 1 if no band is specified. It also by default returns only pixels that have values." msgstr "" -#: ../../en/rasters.rst:503 +#: ../../en/rasters.rst:653 msgid "Which outputs:" msgstr "" -#: ../../en/rasters.rst:507 +#: ../../en/rasters.rst:657 msgid "and if we inspect using the geometry viewer, we'd see:" msgstr "" -#: ../../en/rasters.rst:511 +#: ../../en/rasters.rst:661 msgid "If we want all pixels of all our bands, we'd need to do something like below. Note the differences in this example from previous." msgstr "" -#: ../../en/rasters.rst:514 +#: ../../en/rasters.rst:664 msgid "1. Setting :command:`exclude_nodata_value` to make sure all pixels are returned so that our sets of calls return the same number of rows. The rows out of the function will be naturally in the same order." msgstr "" -#: ../../en/rasters.rst:517 +#: ../../en/rasters.rst:667 msgid "2. Using the `PostgreSQL ROWS FROM constructor `_ , and aliasing each set of columns from our function output with names. So for example the band 1 columns (geom, val, x, y) are renamed to g1, v1, x1, x2" msgstr "" -#: ../../en/rasters.rst:538 +#: ../../en/rasters.rst:688 msgid "We used CROSS JOIN LATERAL in these examples because we wanted to be explicit what we are doing. Since these are all set returning functions, you can replace CROSS JOIN LATERAL with , for short-hand. We'll use a , in the next set of examples" msgstr "" -#: ../../en/rasters.rst:543 +#: ../../en/rasters.rst:694 +msgid "Dumping polygons with ST_DumpAsPolygons" +msgstr "" + +#: ../../en/rasters.rst:696 msgid "Raster also introduces an additional composite type called a :command:`geomval`. Consider a :command:`geomval` as the offspring of a geometry and raster. It contains a geometry and it contains a pixel value." msgstr "" -#: ../../en/rasters.rst:547 +#: ../../en/rasters.rst:700 msgid "You will find several raster functions that return geomvals." msgstr "" -#: ../../en/rasters.rst:549 +#: ../../en/rasters.rst:702 msgid "A commonly used function that outputs geomvals is `ST_DumpAsPolygons `_, which returns a set of contiguous pixels with the same value as a polygon. Again this by default will only check band 1 and exclude no data values unless you override. This example selects only polygons from band 2. You can also apply filters to the values. For most use cases, :command:`ST_DumpAsPolygons` is a better option than :command:`ST_PixelAsPolygons` as it will return far fewer rows." msgstr "" -#: ../../en/rasters.rst:554 +#: ../../en/rasters.rst:707 msgid "This will output 6 rows, and return polygons corresponding to the letters in \"Raster\"." msgstr "" -#: ../../en/rasters.rst:565 +#: ../../en/rasters.rst:718 msgid "Note that it doesn't return a single geometry, because it finds continguous set of pixels with the same value that form a polygon. Even though all these values are the same, they are not continguous." msgstr "" -#: ../../en/rasters.rst:571 +#: ../../en/rasters.rst:724 msgid "A common approach to produce more complex geometries is to group by the values and union." msgstr "" -#: ../../en/rasters.rst:581 +#: ../../en/rasters.rst:734 msgid "This will give you 2 rows back corresponding to the words \"Raster\" and \"Hello\"." msgstr "" -#: ../../en/rasters.rst:585 +#: ../../en/rasters.rst:737 +msgid "Statistics" +msgstr "" + +#: ../../en/rasters.rst:738 +msgid "The most important thing to understand about rasters is that they are statistical tools for storing data in arrays, that you may happen to be able to make look pretty on a screen." +msgstr "" + +#: ../../en/rasters.rst:741 +msgid "You can find a menu of these statistical functions in `Raster Band Statistics `_." +msgstr "" + +#: ../../en/rasters.rst:745 +msgid "ST_SummaryStatsAgg and ST_SummaryStats" +msgstr "" + +#: ../../en/rasters.rst:747 +msgid "Want all stats for a set or rasters, reach for the function `ST_SummaryStatsAgg `_." +msgstr "" + +#: ../../en/rasters.rst:749 +msgid "This query takes about 10 seconds and gives you a summary of the whole table:" +msgstr "" + +#: ../../en/rasters.rst:756 +msgid "Outputs:" +msgstr "" + +#: ../../en/rasters.rst:765 +msgid "Which tells we have a lot of pixels and our max elevation is 411 ft." +msgstr "" + +#: ../../en/rasters.rst:767 +msgid "If you have built overviews, and just need a rough estimate of your mins, maxs, and means use one of your overviews. This next query returns roughly the same values for mins, maxs, and means as the prior but in about 1 second instead of 10." +msgstr "" + +#: ../../en/rasters.rst:776 +msgid "Now armed with this bit of information, we can ask more questions." +msgstr "" + +#: ../../en/rasters.rst:779 +msgid "ST_Histogram" +msgstr "" + +#: ../../en/rasters.rst:781 +msgid "Generally you won't want stats for your whole table, but instead just stats for a particular area, in that case, you'll want to also employ our old friends :command:`ST_Intersects` and :command:`ST_Clip`. If you are also in need of a raster statistics function that doesn't have an aggregate version, you'll want to carry :command:`ST_Union` along for the ride." +msgstr "" + +#: ../../en/rasters.rst:786 +msgid "For this next example we'll use a different stats function `ST_Histogram `_ which has no aggregate equivalent, and for this particular variant, is a set returning function. We are using the same area of interest as some prior examples, but we also need to employ geometry :command:`ST_Transform` to transform our NY state plane meters geometry to our NYC State Plane feet rasters. It is almost always more performant to transform the geometry instead of raster and definitely if your geometry is just a single one." +msgstr "" + +#: ../../en/rasters.rst:803 +msgid "the above query completes in under 60ms and outputs:" +msgstr "" + +#: ../../en/rasters.rst:817 +msgid "Creating Derivative Rasters" +msgstr "" + +#: ../../en/rasters.rst:818 +msgid "PostGIS raster comes packaged with a number of functions for editing rasters. These functions are both used for editing as well as creating derivative raster data sets. You will find these listed in `Raster Editors `_ and `Raster Management `_." +msgstr "" + +#: ../../en/rasters.rst:824 +msgid "Transforming rasters with ST_Transform" +msgstr "" + +#: ../../en/rasters.rst:825 +msgid "Most of our data is in NY State Plane meters (SRID: 26918), however our DEM raster dataset is in NY State Plane feet (SRID: 2263). For the least cumbersome workflow, we need our core datasets to be in the same spatial reference system." +msgstr "" + +#: ../../en/rasters.rst:829 +msgid "The `raster ST_Transform `_ is the function most suited for this job." +msgstr "" + +#: ../../en/rasters.rst:831 +msgid "In order to create a new nyc dem dataset in NY State Plane meters, we'll do the following:" +msgstr "" + +#: ../../en/rasters.rst:841 +msgid "The above on my system took about 1.5 minutes. For a larger data set it would take much longer." +msgstr "" + +#: ../../en/rasters.rst:844 +msgid "The aforementioned examples used two variants of the :command:`ST_Transform` raster function. The first was to get a reference raster that will be used to transform the other raster tiles to guarantee that all tiles have the same alignment. Note the second variant of :command:`ST_Transform` used doesn't even take an input SRID. This is because the SRID and all the pixel scale and block sizes are read from the reference raster. If you used `ST_Transform(rast, srid)` form, then all your rasters might come out with different alignment making it impossible to apply an operation such as :command:`ST_Union` on them." +msgstr "" + +#: ../../en/rasters.rst:851 +msgid "The only problem with the aforementioned :command:`ST_Transform` approach is that when you transform, the transformed often exists in other tiles. If you looked at the above output closely enough by outputting the convex hull of the rasters, in the next example" +msgstr "" + +#: ../../en/rasters.rst:855 +msgid "you'd see annoying overlaps around the borders." +msgstr "" + +#: ../../en/rasters.rst:864 +msgid "viewed in pgAdmin would look something like:" +msgstr "" + +#: ../../en/rasters.rst:870 +msgid "Using ST_MakeEmptyCoverage to create even tiled rasters" +msgstr "" + +#: ../../en/rasters.rst:871 +msgid "A better approach, albeit a bit slower, is to define your own coverage tile structure from scratch using `ST_MakeEmptyCoverage `_ and then find the intersecting tiles for each new tile, and ST_Union these and then use `ST_Transform(ref, ST_Union...)` to create each tile." +msgstr "" + +#: ../../en/rasters.rst:875 +msgid "For this we'll be using quite a few functions, we learned about earlier." +msgstr "" + +#: ../../en/rasters.rst:900 +msgid "Repeating the same exercise as earlier:" +msgstr "" + +#: ../../en/rasters.rst:909 +msgid "viewed in pgAdmin we no longer have overlaps:" +msgstr "" + +#: ../../en/rasters.rst:913 +msgid "On my system this took ~10 minutes and returned 3879 rows. After the creation of the table, we'll want to do the usual of adding a spatial index, primary key, and constraints as follows:" +msgstr "" + +#: ../../en/rasters.rst:928 +msgid "Which should take under 2 minutes for this dataset." +msgstr "" + +#: ../../en/rasters.rst:931 +msgid "Creating overview tables with ST_CreateOverview" +msgstr "" + +#: ../../en/rasters.rst:933 +msgid "Just as with our original dataset, it would be useful to have overview tables to speed up performance of some operations. `ST_CreateOverview `_ is a function fit for that purpose. You can use :command:`ST_CreateOverview` to create overviews also if you neglected to create one during the raster2pgsql load or you decided, you need more overviews." +msgstr "" + +#: ../../en/rasters.rst:939 +msgid "We'll create level 2 and 3 overviews as we had done with our original using this code." +msgstr "" + +#: ../../en/rasters.rst:946 +msgid "This process sadly takes a while, and a longer while the more rows you have so be patient. For this dataset it took about 3-5 minutes for the overview factor `2` and 1 minute for the overview factor `3`." +msgstr "" + +#: ../../en/rasters.rst:949 +msgid "The :command:`ST_CreateOverView` function also adds in the needed constraints so the columns appear with full detail in the `raster_columns` and `raster_overviews` catalogs. It does not add indexes to them though and also does not add an rid column. The rid column is probably not necessary unless you need a primary key to edit with. You would probably want an index which you can create with the following:" +msgstr "" + +#: ../../en/rasters.rst:964 +msgid "ST_CreateOverview has an optional argument for denoting the sampling method. If not specified it uses the default `NearestNeighbor` which is generally the fastest to compute but may not be ideal. Resampling methods is beyond the scope of this workshop." +msgstr "" + +#: ../../en/rasters.rst:970 +msgid "The intersection of rasters and geometries" +msgstr "" + +#: ../../en/rasters.rst:971 +msgid "There are a couple of functions commonly used to compute intersections of rasters and geometries. We've already seen :command:`ST_Clip` in action which returns the intersection of a raster and geometry as a raster, but there are others. For point data, the most commonly used is :command:`ST_Value` and then there is the :command:`ST_Intersection` which has several overloads some returning rasters and some returning a set of `geomval`." +msgstr "" + +#: ../../en/rasters.rst:979 +msgid "Pixel values at a geometric Point" +msgstr "" + +#: ../../en/rasters.rst:981 +msgid "If you need to return values from rasters based on intersection of several ad-hoc geometry points, you'll use `ST_Value `_ or it's nearest relative `ST_NearestValue `_." +msgstr "" + +#: ../../en/rasters.rst:995 +msgid "This example takes about 1 second to return 2444 rows. If you used :command:`ST_Intersects` instead of :command:`&&`, the process would take about 3 seconds. The reason `ST_Intersects` is slower is that it performs an additional recheck in some cases a pixel by pixel check. If you expect all your points to be represented with data in your raster set and your rasters represent a coverage (a continguous set non-overlapping raster tiles), then `&&` is generally a speedier option." +msgstr "" + +#: ../../en/rasters.rst:1000 +msgid "If your raster data is not densely populated or you have overlapping rasters (e.g. they represent different observations in time), or they are skewed (not axis aligned) then there is an advantage to having ST_Intersects weed out the false positives." +msgstr "" + +#: ../../en/rasters.rst:1006 +msgid "ST_Intersection raster style" +msgstr "" + +#: ../../en/rasters.rst:1007 +msgid "Just as you can compute the intersection of two geometries using :command:`ST_Intersection`, you can compute intersection of two rasters or a raster and a geometry using `raster ST_Intersection `_." +msgstr "" + +#: ../../en/rasters.rst:1011 +msgid "What you get out of this beast, are two different kinds of things:" +msgstr "" + +#: ../../en/rasters.rst:1013 +msgid "Intersect a geometry with a raster, and you get a set of `geomval` offspring. Perhaps one, but most often many." +msgstr "" + +#: ../../en/rasters.rst:1016 +msgid "Intersect 2 rasters and you get a single `raster` back." +msgstr "" + +#: ../../en/rasters.rst:1018 +msgid "The golden rule for both raster intersection and geometry intersection is that both parties involved must have the same spatial reference system. For raster/raster, they also have to have same alignment." +msgstr "" + +#: ../../en/rasters.rst:1022 +msgid "Here is an example which answers a question you may have been curious about. If we bucket our elevations into 5 buckets of elevation values, which elevation range results in the most gun fatalities? We know based on our earlier summary statistics that `0` is the lowest value and `411` is the highest value for elevation in our nyc dem dataset, so we use that as min and max value for our `width_bucket `_ call." +msgstr "" + +#: ../../en/rasters.rst:1044 +msgid "Is there an important correlation between gun homicides and elevation? Probably not." +msgstr "" + +#: ../../en/rasters.rst:1048 +msgid "Let's take a look at raster / raster intersection:" +msgstr "" + +#: ../../en/rasters.rst:1057 +msgid "What we get are two rows with NULLLs, and if you have your PostgreSQL set to show notices, you'll see:" +msgstr "" + +#: ../../en/rasters.rst:1059 +msgid "**NOTICE: The two rasters provided do not have the same alignment. Returning NULL**" +msgstr "" + +#: ../../en/rasters.rst:1061 +msgid "In order to fix this, we can align one to the other as it's coming out of the gate using `ST_Resample `_." +msgstr "" + +#: ../../en/rasters.rst:1071 +msgid "Let's also roll it up into a single stats record" +msgstr "" + +#: ../../en/rasters.rst:1083 +msgid "which outputs:" +msgstr "" + +#: ../../en/rasters.rst:1094 msgid "Map Algebra Functions" msgstr "" -#: ../../en/rasters.rst:586 -msgid "Map algebra is the idea that you can do math on your pixel values. The :command:`ST_Union` function covered earlier is a special fast case of map algebra. Then there are the `ST_MapAlgebra `_ family of functions which allow you to define your own crazy math, but at cost of performance." +#: ../../en/rasters.rst:1095 +msgid "Map algebra is the idea that you can do math on your pixel values. The :command:`ST_Union` and :command:`ST_Intersection` functions covered earlier are a special fast case of map algebra. Then there are the `ST_MapAlgebra `_ family of functions which allow you to define your own crazy math, but at cost of performance." msgstr "" -#: ../../en/rasters.rst:592 +#: ../../en/rasters.rst:1103 msgid "People have the habit of jumping to :command:`ST_MapAlgebra`, probably cause the name sounds so cool and sophisticated. Who wouldn't want to tell their friends, \"I'm using a function called ST_MapAlgebra.\" My advice, explore other functions before you jump for that shot-gun. Your life will be simpler and your performance will be 100 times better, and your code will be shorter." msgstr "" -#: ../../en/rasters.rst:598 +#: ../../en/rasters.rst:1109 +msgid "Before we showcase `ST_MapAlgebra`, we'll explore other functions that fit under the `Map Algebra` family of functions and generally have better performance than `ST_MapAlgebra`." +msgstr "" + +#: ../../en/rasters.rst:1113 +msgid "Reclassify your raster using ST_Reclass" +msgstr "" + +#: ../../en/rasters.rst:1115 msgid "An often overlooked map-algebraish function is the `ST_Reclass `_ function, who sits in the background waiting for someone to discover the power and speed it can offer." msgstr "" -#: ../../en/rasters.rst:602 +#: ../../en/rasters.rst:1119 msgid "What does **ST_Reclass** do? It as the name implies, reclassifies your pixel values based on minimalist range algebra." msgstr "" + +#: ../../en/rasters.rst:1121 +msgid "Lets revisit our NYC Dems. Perhaps we only care about classifying our elevations as 1) low, 2) medium, 3) high , and 4) really high. We don't need 411 values, we just need 4. With that said lets do some reclassifying." +msgstr "" + +#: ../../en/rasters.rst:1124 +msgid "The classification scheme is governed by the `reclass expression `_." +msgstr "" + +#: ../../en/rasters.rst:1140 +msgid "Which would output:" +msgstr "" + +#: ../../en/rasters.rst:1152 +msgid "If this were a classification scheme we preferred, we could create a new table using the ST_Reclass to recompute each tile." +msgstr "" + +#: ../../en/rasters.rst:1155 +msgid "Coloring your rasters with ST_ColorMap" +msgstr "" + +#: ../../en/rasters.rst:1156 +msgid "The `ST_ColorMap `_ function is another mapalgebraish function that reclassifies your pixel values. Except it is band creating. It converts a single band raster such as our Dems into a visually presentable 3 or 4 banded raster." +msgstr "" + +#: ../../en/rasters.rst:1160 +msgid "You could use one of the built-in colormaps as below if you don't want to fuss with creating one." +msgstr "" + +#: ../../en/rasters.rst:1171 +msgid "Which looks like:" +msgstr "" + +#: ../../en/rasters.rst:1175 +msgid "The bluer the color the lower the elevation and the redder the color the higher the elevation." +msgstr "" diff --git a/postgis-intro/sources/locale/ja/LC_MESSAGES/rasters.po b/postgis-intro/sources/locale/ja/LC_MESSAGES/rasters.po index 376b773e..17cd270b 100644 --- a/postgis-intro/sources/locale/ja/LC_MESSAGES/rasters.po +++ b/postgis-intro/sources/locale/ja/LC_MESSAGES/rasters.po @@ -9,7 +9,7 @@ msgid "" msgstr "" "Project-Id-Version: Introduction to PostGIS 1.1\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2023-01-13 00:30-0500\n" +"POT-Creation-Date: 2023-01-25 04:15-0500\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" @@ -31,378 +31,826 @@ msgstr "" msgid "Although pretty pictures such as those you see on your TV screen are rasters, rasters may not be that exciting to look at. In a nutshell, a raster is a matrix, pinned on a coordinate system, that has values that can represent anything you want them to represent." msgstr "" -#: ../../en/rasters.rst:15 -msgid "Since rasters live in cartesian space, rasters can interact with geometries. PostGIS offers many functions that take as input both rasters and geometries. Also many operations applied to rasters will result in geometries. Common ones are the `ST_Polygon`, `ST_Envelope`, `ST_ConvexHull`, and `ST_MinConvexHull` as shown below." +#: ../../en/rasters.rst:17 +msgid "Since rasters live in cartesian space, rasters can interact with geometries. PostGIS offers many functions that take as input both rasters and geometries. Many operations applied to rasters will result in geometries. Common ones are the `ST_Polygon`, `ST_Envelope`, `ST_ConvexHull`, and `ST_MinConvexHull` as shown below. When you cast a raster to a geometry, what is output is the `ST_ConvexHull` of the raster." msgstr "" -#: ../../en/rasters.rst:21 -msgid "The raster format is commonly used to store elevation data, temperature data, satellite data, and thematic data representing things like environmental contamination, population density, and environmental hazard occurrences." +#: ../../en/rasters.rst:24 +msgid "The raster format is commonly used to store elevation data, temperature data, satellite data, and thematic data representing things like environmental contamination, population density, and environmental hazard occurrences. You can use rasters to store any numeric data that has a meaningful coordinate location. The only restriction is that for all data in a specific band the numeric data types have to be the same." msgstr "" -#: ../../en/rasters.rst:23 -msgid "Although raster data can be created from scratch in PostGIS, a more common approach is to load raster data from various formats using the `raster2pgsql `_ command line tool packaged with PostGIS. Before all of that, you must enable raster support in your database by running the command:" +#: ../../en/rasters.rst:28 +msgid "Although raster data can be created from scratch in PostGIS, a more common approach is to load raster data from various formats using the :command:`raster2pgsql` command line tool packaged with PostGIS. Before all of that, you must enable raster support in your database by running the command:" msgstr "" -#: ../../en/rasters.rst:30 +#: ../../en/rasters.rst:37 msgid "Creating Rasters From Geometries" msgstr "" -#: ../../en/rasters.rst:31 +#: ../../en/rasters.rst:38 msgid "We'll start off by first creating raster data from vector data, and then move on to the more exciting approach of loading data from a raster source. You will find that raster data is available in abundance and often free from various government sites." msgstr "" -#: ../../en/rasters.rst:34 +#: ../../en/rasters.rst:41 msgid "We'll start by converting some geometries into rasters using `ST_AsRaster `_ function as follows." msgstr "" -#: ../../en/rasters.rst:48 -msgid "The above example CREATEs a table (**rasters**) from geometries formed from letters using the PostGIS 3.2+ `ST_Letters `_ function. Rasters similar to geometries, can take advantage of spatial indexes. The spatial index used for raster is a functional index that indexes the geometry convexhull of the raster. When loading data with :command:`raster2pgsql` with the :command:`I` switch, the :command:`CREATE INDEX` step is done for you." +#: ../../en/rasters.rst:55 +msgid "The above example CREATEs a table (**rasters**) from geometries formed from letters using the PostGIS 3.2+ `ST_Letters `_ function. Rasters similar to geometries, can take advantage of spatial indexes. The spatial index used for raster is a functional index that indexes the geometry convexhull of the raster." msgstr "" -#: ../../en/rasters.rst:53 -msgid "You can see some useful metadata of your rasters with the following query which utilizes the postgis raster functions `ST_Count `_ function to count the number of pixels that have data and the `ST_MetaData `_ function to provide all sorts of useful background info for our rasters." +#: ../../en/rasters.rst:58 +msgid "You can see some useful metadata of your rasters with the following query which utilizes the postgis raster `ST_Count `_ function to count the number of pixels that have data and the `ST_MetaData `_ function to provide all sorts of useful background info for our rasters." msgstr "" -#: ../../en/rasters.rst:71 -msgid "There are two levels of raster functions. There are functions such as ST_MetaData that work at the raster level and there are functions such as :command:`ST_Count` function and :command:`ST_BandMetaData `_ function that work at the band level. Most functions in postgis raster that work at the band level, work with only one band at a time, and assume the band you want is `1`." +#: ../../en/rasters.rst:76 +msgid "There are two levels of raster functions. There are functions such as ST_MetaData that work at the raster level and there are functions such as :command:`ST_Count` function and `ST_BandMetaData `_ function that work at the band level. Most functions in postgis raster that work at the band level, work with only one band at a time, and assume the band you want is `1`." msgstr "" -#: ../../en/rasters.rst:78 +#: ../../en/rasters.rst:83 +msgid "If you have a multi-band raster, and you need to count the pixel not no-data values in a band other than 1, you would explicitly specify the band number as follows `ST_Count(rast,2)`." +msgstr "" + +#: ../../en/rasters.rst:85 msgid "Note how all the rasters have a 150x150 dimension. This is not ideal. This means that in order to force that, our rasters, are squished in all sorts of ways. If only we could see the ugliness of the rasters before us." msgstr "" -#: ../../en/rasters.rst:81 -msgid "If you have a multi-band raster, and you need to count the pixel not no-data values in a band other than 1, you would explicitly specify the band number as follows `ST_Count(rast,2)`." +#: ../../en/rasters.rst:89 +msgid "Loading Rasters using raster2pgsql" msgstr "" -#: ../../en/rasters.rst:85 +#: ../../en/rasters.rst:90 +msgid "`raster2pgsql `_ is a command-line tool often packaged with PostGIS. If you are on windows and used application stackbuilder PostGIS Bundle, you'll find :command:`raster2pgsql.exe` in the folder ``C:\\Program Files\\PostgreSQL\\15\\bin`` where the *15* should be replaced with the version of PostgreSQL you are running." +msgstr "" + +#: ../../en/rasters.rst:93 +msgid "If you are using Postgres.App, you'll find raster2pgsql among the other `Postgres.app CLI Tools `_." +msgstr "" + +#: ../../en/rasters.rst:95 +msgid "On Ubuntu and Debian, you will need" +msgstr "" + +#: ../../en/rasters.rst:101 +msgid "to have the PostGIS commandline tools installed. This may install an additional version of PostgreSQL as well. You can see a list of clusters in Debian/Ubuntu using the :command:`pg_lsclusters` command and drop them using the :command:`pg_dropcluster` command." +msgstr "" + +#: ../../en/rasters.rst:106 +msgid "For this and later exercises, we'll be using `nyc_dem.tif` found in the file `PG Raster Workshop Dataset https://postgis.net/stuff/workshop-data/postgis_raster_workshop.zip `_. For some geometry/raster examples, we will also be using NYC data loaded from prior chapters. In-lieu of loading the tif, you can restore the `nyc_dem.backup` included in the zip file in your database using the :command:`pg_restore` commandline tool or the pgAdmin **Restore** menu." +msgstr "" + +#: ../../en/rasters.rst:112 +msgid "This raster data was sourced from `NYC DEM 1-foot Integer `_ which is a 3GB DEM tif representing elevation relative to sea level with buildings and overwater removed. We then created a lower res version of it." +msgstr "" + +#: ../../en/rasters.rst:115 +msgid "The :command:`rasterpgsql` tool is similar to the :command:`shp2gpsql` except instead of loading ESRI shapefiles into PostGIS geometry/geography tables, it loads any GDAL supported raster format into raster tables. Just like :command:`shp2pgsql` you can pass it a spatial reference id (SRID) of the source. Unlike :command:`shp2pgsql` it can infer the spatial references system of the source data if your source data has suitable metadata." +msgstr "" + +#: ../../en/rasters.rst:119 +msgid "For a full exposure of all the possible switches offered refer to `raster2pgsql options `_." +msgstr "" + +#: ../../en/rasters.rst:121 +msgid "Some other notable options :command:`raster2pgsql` offers which we will not cover are:" +msgstr "" + +#: ../../en/rasters.rst:123 +msgid "Ability to denote the SRID of the source. Instead, we'll rely on raster2pgsql guessing skills." +msgstr "" + +#: ../../en/rasters.rst:124 +msgid "Ability to set the `nodata` value, when not specified, raster2pgsql tries to infer from the file." +msgstr "" + +#: ../../en/rasters.rst:125 +msgid "Abiliity to load out-of-database rasters." +msgstr "" + +#: ../../en/rasters.rst:127 +msgid "To load all the tif files in our folder and also create overviews, we would run the below." +msgstr "" + +#: ../../en/rasters.rst:133 +msgid "-d to drop the tables if they already exist" +msgstr "" + +#: ../../en/rasters.rst:134 +msgid "The above command uses `-e` to do load immediately instead of committing in a transaction" +msgstr "" + +#: ../../en/rasters.rst:135 +msgid "`-C` set raster constraints, this is useful for `raster_columns` to show info. You may want to combine with `-x` to exclude the extent constraint, which is a slow constraint to check and also hampers future loads in the table." +msgstr "" + +#: ../../en/rasters.rst:138 +msgid "`-M` to vacuum and analyze after load, to improve query planner statistics" +msgstr "" + +#: ../../en/rasters.rst:139 +msgid "`-Y` to use copy in batches of 50. If you are running PostGIS 3.3 or higher, you can use `-Y 1000` to have copy be in batches of 1000, or even higher number. This will run faster, but will use more memory." +msgstr "" + +#: ../../en/rasters.rst:141 +msgid "`-l 2,3` to create over view tables: `o_2_ncy_dem` and `o_3_nyc_dem`. This is useful for viewing data." +msgstr "" + +#: ../../en/rasters.rst:142 +msgid "-I to create a spatial index" +msgstr "" + +#: ../../en/rasters.rst:143 +msgid "`-F` to add file name, if you have only one tif file, this is kinda pointless. If you had multiple, this would be useful to tell you what file each row came from." +msgstr "" + +#: ../../en/rasters.rst:145 +msgid "`-t` to set the block size. Note if you are not sure the best size use, use `-t auto` instead and raster2pgql will use the same tiling as what was in the tif. The output will tell you what the blocksize is it chose. Cancel if it looks huge or weird. The original file had a size of 300x7 which is not ideal." +msgstr "" + +#: ../../en/rasters.rst:149 +msgid "Use :command:`psql` to run the generated sql against the database. If you want to dump to a file instead, use `> nyc_dem.sql`" +msgstr "" + +#: ../../en/rasters.rst:153 +msgid "For this example, we have only one tif file, so we could instead specify the full file name, instead of `*.tif`. If the files are not in your current directory, you can also specify a folder path with `*.tif`." +msgstr "" + +#: ../../en/rasters.rst:158 +msgid "If you are on windows and need to reference the folder, make sure to include the drive letter such as `C:/workshop/*.tif`" +msgstr "" + +#: ../../en/rasters.rst:161 +msgid "You'll often hear in PostGIS lingo, the term **raster tile** and **raster** used somewhat interchangeably. A raster tile really corresponds to a particular raster in a raster column which is a subset of a bigger raster, such as this NYC dem data we just loaded. This is because when rasters are loaded into PostGIS from big raster files, they chopped into many rows to make them manageable. Each raster in each row then is a part of a bigger raster. Each tile covers same size area denoted by the blocksize you specified. Rasters are sadly limited by the 1GB PostgreSQL `TOAST `_ limit and also the slow process of detoasting and so we need to chop up in order to achieve decent performance or to even store them." +msgstr "" + +#: ../../en/rasters.rst:170 msgid "Viewing Rasters in Browser" msgstr "" -#: ../../en/rasters.rst:86 -msgid "Although pgAdmin and psql have no mechanism yet to view postgis rasters, we have a couple of options. For smallish rasters the easiest is to output to a web-friendly raster format such as PNG using batteries included postgis raster functions like `ST_AsPNG` or `ST_AsGDALRaster` listed in `PostGIS Raster output functions `_. As your rasters get larger, you'll want to graduate to a tool such as QGIS to view them in all their glory or the GDAL family of commandline tools such as gdal_translate to export them to other raster formats. Remember though, postgis rasters are built for analysis, not for generating pretty pictures for you to look at." +#: ../../en/rasters.rst:171 +msgid "Although pgAdmin and psql have no mechanism yet to view postgis rasters, we have a couple of options. For smallish rasters the easiest is to output to a web-friendly raster format such as PNG using batteries included postgis raster functions like `ST_AsPNG` or `ST_AsGDALRaster` listed in `PostGIS Raster output functions `_. As your rasters get larger, you'll want to graduate to a tool such as QGIS to view them in all their glory or the GDAL family of commandline tools such as :command:`gdal_translate` to export them to other raster formats. Remember though, postgis rasters are built for analysis, not for generating pretty pictures for you to look at." msgstr "" -#: ../../en/rasters.rst:93 +#: ../../en/rasters.rst:178 msgid "One caveat, by default all different raster types outputs are disabled. In order to utilize these, you'll need to enable drivers, all or a subset as detailed in `Enable GDAL Raster drivers `_" msgstr "" -#: ../../en/rasters.rst:101 +#: ../../en/rasters.rst:186 msgid "If you don't want to have to do this for each connection, you can set at the database level using:" msgstr "" -#: ../../en/rasters.rst:107 +#: ../../en/rasters.rst:192 msgid "Each new connection to the database will use that setting." msgstr "" -#: ../../en/rasters.rst:109 +#: ../../en/rasters.rst:194 msgid "Run the below query and copy and paste the output into the address bar of your web browser." msgstr "" -#: ../../en/rasters.rst:120 +#: ../../en/rasters.rst:205 msgid "For the rasters created thus far, we didn't specify the number of bands nor did we even define their relation to earth. As such our rasters have an unknown spatial reference system (0)." msgstr "" -#: ../../en/rasters.rst:123 +#: ../../en/rasters.rst:208 msgid "You can think of a rasters exoskeletal as a geometry. A matrix encased in a geometric envelop. In order to do useful analysis, we need to georeference our rasters, meaning we want each pixel (rectangle) to represent some meaningful plot of space." msgstr "" -#: ../../en/rasters.rst:128 +#: ../../en/rasters.rst:213 msgid "The `ST_AsRaster` has many overloaded representations. The earlier example used the simplest such implementation and accepted the default arguments which are 8BUI and 1 band, with no data being 0. If you need to use the other variants, you should use the named arguments call syntax so that you don't accidentally fall into the wrong variant of the function or get **function is not unique** errors." msgstr "" -#: ../../en/rasters.rst:133 -msgid "If you start with a geometry that has a spatial reference system, you'll end up with a raster with same spatial reference system. In this next example, we'll plop our words in New York in bright cheery colors. We will also use pixel scale instead of width and height so that our raster pixel sizes represent 1 meter x 1 meter of space." +#: ../../en/rasters.rst:221 +msgid "If you start with a geometry that has a spatial reference system, you'll end up with a raster with same spatial reference system. In this next example, we'll plop our words in New York in bright cheery colors. We will also use pixel scale instead of width and height so that our raster pixel sizes represent 1 meter x 1 meter of space." msgstr "" -#: ../../en/rasters.rst:155 +#: ../../en/rasters.rst:244 msgid "If we then look at this, we'll see a non-squashed colored geometry." msgstr "" -#: ../../en/rasters.rst:166 +#: ../../en/rasters.rst:255 msgid "Repeat for Raster:" msgstr "" -#: ../../en/rasters.rst:177 +#: ../../en/rasters.rst:266 msgid "What is more telling, if we rerun the" msgstr "" -#: ../../en/rasters.rst:184 +#: ../../en/rasters.rst:273 msgid "Observe the metadata of the New York entries. They have the New York state plane meter spatial reference system. They also have the same scale. Since each unit is 1x1 meter, the width of the word **Raster** is now wider than **Hello**." msgstr "" -#: ../../en/rasters.rst:199 +#: ../../en/rasters.rst:288 msgid "Raster Spatial Catalog tables" msgstr "" -#: ../../en/rasters.rst:200 -msgid "Similar to the geometry and geography types, raster has a set of catalogs that show you all raster columns in your database. These are `raster_columns and raster_overviews `_. Both of these are views similar to the `geometry_columns` and `geography_columns`." +#: ../../en/rasters.rst:289 +msgid "Similar to the geometry and geography types, raster has a set of catalogs that show you all raster columns in your database. These are `raster_columns and raster_overviews `_." msgstr "" -#: ../../en/rasters.rst:210 +#: ../../en/rasters.rst:295 +msgid "raster_columns" +msgstr "" + +#: ../../en/rasters.rst:297 +msgid "The `raster_columns` view to the sibling to the `geometry_columns` and `geography_columns`, providing much the same data and more, but for raster columns." +msgstr "" + +#: ../../en/rasters.rst:305 msgid "Explore the table, and you'll find this:" msgstr "" -#: ../../en/rasters.rst:219 -msgid "a very disappointing row of largely unfilled information." +#: ../../en/rasters.rst:317 +msgid "a disappointing row of largely unfilled information for the `rasters` table." msgstr "" -#: ../../en/rasters.rst:221 +#: ../../en/rasters.rst:319 msgid "Unlike geometry and geography, raster does not support type modifiers, because type modifier space is too limited and there are more critical properties than what can fit in a type modifier." msgstr "" -#: ../../en/rasters.rst:224 -msgid "Raster instead relies on constraints, and reads these constraints back as part of the view. So let's try to add some constraints to our table." +#: ../../en/rasters.rst:322 +msgid "Raster instead relies on constraints, and reads these constraints back as part of the view." +msgstr "" + +#: ../../en/rasters.rst:324 +msgid "Look at the other rows from the tables we loaded using :command:`raster2pgsql`. Because we used the `-C` switch :command:`raster2pgsql` added constraints for the srid and other info it was able to read from the tif or that we passed in. The overview tables generated with the `-l` switch `o_2_nyc_dem` and `o_3_nyc_dem` show up as well." msgstr "" -#: ../../en/rasters.rst:232 -msgid "And you'll be bombarded with a whole bunch of notices about how your raster data is mess and nothing can be constrained. If you look at raster_columns again, still the same disappointing story of many blank rows." +#: ../../en/rasters.rst:327 +msgid "Let's try to add some constraints to our table." msgstr "" -#: ../../en/rasters.rst:236 +#: ../../en/rasters.rst:334 +msgid "And you'll be bombarded with a whole bunch of notices about how your raster data is a mess and nothing can be constrained. If you look at raster_columns again, still the same disappointing story of many blank rows for `rasters`." +msgstr "" + +#: ../../en/rasters.rst:338 msgid "In order for constraints to be applied, all rasters in your table must be constrainable by at least one rule." msgstr "" -#: ../../en/rasters.rst:239 +#: ../../en/rasters.rst:341 msgid "We can perhaps do this, let's just lie and say all our data is in New York State plane." msgstr "" -#: ../../en/rasters.rst:252 +#: ../../en/rasters.rst:355 msgid "Ah progress:" msgstr "" -#: ../../en/rasters.rst:261 +#: ../../en/rasters.rst:364 msgid "The more you can constrain all your rasters, the more columns you'll see filled in and also the more operations you'll be able to do across all the tiles in your raster. Keep in mind that in some cases, you may not want to apply all constraints." msgstr "" -#: ../../en/rasters.rst:265 +#: ../../en/rasters.rst:368 msgid "For example, if you plan to load more data into your raster table, you'll want to skip the extent constraint since that would require that all rasters are within the extent of the extent constraint." msgstr "" -#: ../../en/rasters.rst:269 -msgid "You'll often here in PostGIS lingo, the term **raster tile** and **raster** used somewhat interchangeably. A raster tile really corresponds to a particular raster in a raster column which is a subset of a bigger raster. This is because when rasters are loaded into PostGIS from big raster files, they are often chopped up to make them manageable." +#: ../../en/rasters.rst:373 +msgid "raster_overviews" +msgstr "" + +#: ../../en/rasters.rst:374 +msgid "Raster overview columns appear both in the `raster_columns` meta catalog and another meta catalog called `raster_overviews`. Overviews are used mostly to speed up viewing at higher zoom levels. They can also be used for quick back of the envelop analysis, providing less accurate stats, but at a much faster speed than applying to the raw raster table." +msgstr "" + +#: ../../en/rasters.rst:379 +msgid "To inspect the overviews, run:" msgstr "" -#: ../../en/rasters.rst:275 -msgid "Exploring Raster Functions" +#: ../../en/rasters.rst:386 +msgid "and you'll see the output:" msgstr "" -#: ../../en/rasters.rst:276 -msgid "The :command:`postgis_raster` extension has over 100 functions to choose from. We'll focus on the ones you will commonly use. PostGIS raster functionality was patterned after the PostGIS geometry support. As such you'll find an overlap of functions between raster and geometry where it makes sense. Common ones you'll use that have equivalent in geometry world are :command:`ST_Intersects`, :command:`ST_SetSRID`, :command:`ST_SRID`, :command:`ST_Union`, :command:`ST_Intersection`, and :command:`ST_Transform`. In addition to those overlapping functions, it offers many functions that work in conjunction with geometry or are very specific to rasters." +#: ../../en/rasters.rst:396 +msgid "The `raster_overviews` table only provides you the overview_factor and the name of the parent table. All this information is something you could have figured out yourself by the `raster2pgsql` naming convention for overviews." msgstr "" -#: ../../en/rasters.rst:285 -msgid "Unioning Rasters" +#: ../../en/rasters.rst:400 +msgid "The `overview_factor` tells you at what resolution the row is with respect to it's parent. An `overview_factor` of `2` means that 2x2 = 4 tiles can fit into one overview_2 tile. Similarly an overview_factor of `1` meants that 2x2x2 = 8 tiles of the original can be shoved into an overview_3 tile." msgstr "" -#: ../../en/rasters.rst:286 +#: ../../en/rasters.rst:407 +msgid "Common Raster Functions" +msgstr "" + +#: ../../en/rasters.rst:408 +msgid "The :command:`postgis_raster` extension has over 100 functions to choose from. PostGIS raster functionality was patterned after the PostGIS geometry support. You'll find an overlap of functions between raster and geometry where it makes sense. Common ones you'll use that have equivalent in geometry world are :command:`ST_Intersects`, :command:`ST_SetSRID`, :command:`ST_SRID`, :command:`ST_Union`, :command:`ST_Intersection`, and :command:`ST_Transform`." +msgstr "" + +#: ../../en/rasters.rst:415 +msgid "In addition to those overlapping functions, it supports the `&&` overlap operator between rasters and between a raster and geometry. It also offers many functions that work in conjunction with geometry or are very specific to rasters." +msgstr "" + +#: ../../en/rasters.rst:419 +msgid "You need a function like :command:`ST_Union` to reconstitute a region. Because performance gets slow, the more pixels a function needs to analyse, you need a fast acting function :command:`ST_Clip` to clip the rasters to just the portions of interest for your analysis." +msgstr "" + +#: ../../en/rasters.rst:423 +msgid "Finally you need :command:`ST_Intersects` or :command:`&&` to zoom in on the raster tiles that contain your areas of interest. The `&&` operator, is a faster process than the `ST_Intersects`. Both can take advantage of raster spatial indexes. We'll cover these bread and butter functions first before moving on to other sections where we will use them in concert with other raster and geometry functions." +msgstr "" + +#: ../../en/rasters.rst:429 +msgid "Unioning Rasters with ST_Union" +msgstr "" + +#: ../../en/rasters.rst:430 msgid "The `ST_Union `_ function for raster, just as the geometry equivalent :command:`ST_Union`, aggregates a set of rasters together into a single raster. However, just as with geometry, not all rasters can be combined together, but the rules for raster unioning are more complicated than geometry rules. In the case of geometries, all you need is to have the same spatial reference system, but for rasters that is not sufficient." msgstr "" -#: ../../en/rasters.rst:294 -msgid "If you were to attempt, the following" +#: ../../en/rasters.rst:438 +msgid "If you were to attempt, the following:" msgstr "" -#: ../../en/rasters.rst:301 +#: ../../en/rasters.rst:445 msgid "You'd be summarily punished with an error:" msgstr "" -#: ../../en/rasters.rst:303 +#: ../../en/rasters.rst:447 msgid "**ERROR: rt_raster_from_two_rasters: The two rasters provided do not have the same alignment SQL state: XX000**" msgstr "" -#: ../../en/rasters.rst:306 +#: ../../en/rasters.rst:450 msgid "What is this same alignment thing, that is preventing you from unioning your precious rasters?" msgstr "" -#: ../../en/rasters.rst:308 +#: ../../en/rasters.rst:452 msgid "In order for rasters to be combined, they need to be on the same grid so to speak. Meaning they must have same pixel sizes, same orientation (the skew), same spatial reference system, and their pixels must not cut into each other, meaning they share the same worldly pixel grid." msgstr "" -#: ../../en/rasters.rst:312 +#: ../../en/rasters.rst:456 msgid "If you try the same query, but just with words we carefully placed in New York." msgstr "" -#: ../../en/rasters.rst:314 +#: ../../en/rasters.rst:458 msgid "Again, the same error. These are the same spatial ref system, the same pixel sizes, and yet it's still not good enough. Because their grids are off." msgstr "" -#: ../../en/rasters.rst:318 +#: ../../en/rasters.rst:462 msgid "We can fix this by shifting the upper left y coordinates ever so slightly and then trying again. If our grids start at integer level since our pixel sizes are whole integer, then the pixels won't cut into each other." msgstr "" -#: ../../en/rasters.rst:333 ../../en/rasters.rst:382 +#: ../../en/rasters.rst:477 ../../en/rasters.rst:526 msgid "Voila it worked, and if we were to view, we'd see something like this:" msgstr "" -#: ../../en/rasters.rst:339 +#: ../../en/rasters.rst:483 msgid "If ever you are unclear why your rasters don't have the same alignment, you can use the function `ST_SameAlignment `_, which will compare 2 rasters or a set of rasters and tell you if they have the same alignment. If you have notices enabled, the NOTICE will tell you what is off with the rasters in question. The `ST_NotSameAlignmentReason `_, instead of just a notice will output the reason. It however only works with two rasters at a time." msgstr "" -#: ../../en/rasters.rst:346 +#: ../../en/rasters.rst:490 msgid "One major way in which the `ST_Union(raster) `_ raster function deviates from the `ST_Union(geometry) `_ geometry function is that it allows for an argument called *uniontype*. This argument by default is set to `LAST` if you don't specify it, which means, take the **LAST** raster pixel values in occasions where the raster pixel values overlap. As a general rule, pixels in a band that are marked as no-data are ignored." msgstr "" -#: ../../en/rasters.rst:352 +#: ../../en/rasters.rst:496 msgid "Just as with most aggregates in PostgreSQL, you can put a :command:`ORDER BY` clause as part of the function call as is done in the prior example. Specifying the order, allows you to control which raster takes priority. So in our prior example, *Raster* trumped *Hello* because *Raster* is alphabetically last." msgstr "" -#: ../../en/rasters.rst:356 +#: ../../en/rasters.rst:500 msgid "Observe, if you switch the order:" msgstr "" -#: ../../en/rasters.rst:366 +#: ../../en/rasters.rst:510 msgid "Then *Hello* trumps *Raster* because Hello is now the last overlaid." msgstr "" -#: ../../en/rasters.rst:368 +#: ../../en/rasters.rst:512 msgid "The :command:`FIRST` union type is the reverse of :command:`LAST`." msgstr "" -#: ../../en/rasters.rst:370 +#: ../../en/rasters.rst:514 msgid "But on occassion, **LAST** may not be the right operation. Let's suppose our rasters represented two different sets of observations from two different devices. These devices measure the same thing, and we aren't sure which is right when they cross paths, so we'd instead like to take the `MEAN` of the results. We'd do this:" msgstr "" -#: ../../en/rasters.rst:386 +#: ../../en/rasters.rst:530 msgid "So instead of trumping, we have a blending of the two forces. In the case of :command:`MEAN` union type, there is no point in specifying order, because the result would be the average of overlapping pixel values." msgstr "" -#: ../../en/rasters.rst:390 +#: ../../en/rasters.rst:534 msgid "Note that for geometries since geometries are vector and thus have no values besides there or not there, there really isn't any ambiguity on how to combine two vectors when they intersect." msgstr "" -#: ../../en/rasters.rst:394 +#: ../../en/rasters.rst:538 msgid "Another feature of the raster :command:`ST_Union` we glossed over, is this idea of if you should return all bands or just some bands. When you don't specify what bands to union, :command:`ST_Union` will combine same banded numbers and use the :command:`LAST` unioning strategy. If you have multiple bands, this may not be what you want to do. Perhaps you only want to union, the second band. In this case, the Green Band and you want the count of pixel values." msgstr "" -#: ../../en/rasters.rst:415 +#: ../../en/rasters.rst:559 msgid "Note in the case of the **COUNT** union type, which counts the number of pixels filled in and returns that value, the result is always a **32BUI** similar to how when you do a :command:`COUNT` in sql, the result is always a bigint, to accommodate large counts." msgstr "" -#: ../../en/rasters.rst:419 +#: ../../en/rasters.rst:563 msgid "In other cases, the band pixel type does not change and is set to the max value or rounded if the amounts exceed the bounds of the type. Why would anyone ever want to count pixels that intersect at a location. Well suppose each of your rasters represent police squadrons and incidents of arrests in the areas. Each value, might represent a different kind of arrest reason. You are doing stats on how many arrests in each region, therefore you only care about the count of arrests." msgstr "" -#: ../../en/rasters.rst:428 +#: ../../en/rasters.rst:572 msgid "Or perhaps, you want to do all bands, but you want different strategies." msgstr "" -#: ../../en/rasters.rst:438 +#: ../../en/rasters.rst:582 msgid "Using the *unionarg[]* variant of the :command:`ST_Union` function, also allows you to shuffle the order of the bands." msgstr "" -#: ../../en/rasters.rst:441 -msgid "Clipping Rasters" +#: ../../en/rasters.rst:585 +msgid "Clipping Rasters with help of ST_Intersects" msgstr "" -#: ../../en/rasters.rst:442 +#: ../../en/rasters.rst:586 msgid "The `ST_Clip `_ function is one of the most widely used functions for PostGIS rasters. The main reason is the more pixels you need to inspect or do operations on, the slower your processing. **ST_Clip** clips your raster to just the area of interest, so you can isolate your operations to just that area." msgstr "" -#: ../../en/rasters.rst:446 +#: ../../en/rasters.rst:590 msgid "This function is also special in that it utilizes the power of geometry to help raster analysis. To reduce the number of pixels, :command:`ST_Union` has to handle, each raster is clipped first to the area we are interested in." msgstr "" -#: ../../en/rasters.rst:458 -msgid "This example showcases several functions working in unison. The :command:`ST_Intersects` function employed is the one packaged with **postgis_raster** and can intersect 2 rasters or a raster and a geometry. Similar to the geometry :command:`ST_Intersects` the raster :command:`ST_Intersects` can take advantage of spatial indexes on the raster or geometry tables." +#: ../../en/rasters.rst:602 +msgid "This example showcases several functions working in unison. The :command:`ST_Intersects` function employed is the one packaged with **postgis_raster** and can intersect 2 rasters or a raster and a geometry. Similar to the geometry :command:`ST_Intersects` the `raster ST_Intersects `_ can take advantage of spatial indexes on the raster or geometry tables." msgstr "" -#: ../../en/rasters.rst:464 +#: ../../en/rasters.rst:609 msgid "Converting Rasters to Geometries" msgstr "" -#: ../../en/rasters.rst:465 -msgid "Rasters can just as easily be morphed into geometries. Lets start with our prior example, but convert it to a polygon using `ST_Polygon `_ function." +#: ../../en/rasters.rst:610 +msgid "Rasters can just as easily be morphed into geometries." +msgstr "" + +#: ../../en/rasters.rst:613 +msgid "The polygon of a raster with ST_Polygon" +msgstr "" + +#: ../../en/rasters.rst:614 +msgid "Lets start with our prior example, but convert it to a polygon using `ST_Polygon `_ function." msgstr "" -#: ../../en/rasters.rst:477 +#: ../../en/rasters.rst:625 msgid "If you click on the geometry viewer in pgAdmin, you can see this in all it's glory without any hacks." msgstr "" -#: ../../en/rasters.rst:481 -msgid "ST_Polygon considers all the pixels that have values (not no-data) in a particular band, and converts them to geometry. Like many other functions in raster, ST_Polygon only considers 1 band. If no band is specified, it will consider only the first band." +#: ../../en/rasters.rst:629 +msgid ":command:`ST_Polygon` considers all the pixels that have values (not no-data) in a particular band, and converts them to geometry. Like many other functions in raster, :command:`ST_Polygon` only considers 1 band. If no band is specified, it will consider only the first band." +msgstr "" + +#: ../../en/rasters.rst:634 +msgid "The pixel rectangles of a raster with ST_PixelAsPolygons" msgstr "" -#: ../../en/rasters.rst:485 +#: ../../en/rasters.rst:635 msgid "Another popularly used function is the `ST_PixelAsPolygons `_ function. You should rarely use :command:`ST_PixelAsPolygons` on a large raster without first clipping because you will end up with millions of rows, one for each pixel." msgstr "" -#: ../../en/rasters.rst:488 +#: ../../en/rasters.rst:638 msgid ":command:`ST_PixelAsPolygons` returns a table consisting of geom, val, x, and y. Where x is the column number, and y is the row number in the raster." msgstr "" -#: ../../en/rasters.rst:491 +#: ../../en/rasters.rst:641 msgid ":command:`ST_PixelAsPolygons` similar to other raster functions works on one band at a time and works on band 1 if no band is specified. It also by default returns only pixels that have values." msgstr "" -#: ../../en/rasters.rst:503 +#: ../../en/rasters.rst:653 msgid "Which outputs:" msgstr "" -#: ../../en/rasters.rst:507 +#: ../../en/rasters.rst:657 msgid "and if we inspect using the geometry viewer, we'd see:" msgstr "" -#: ../../en/rasters.rst:511 +#: ../../en/rasters.rst:661 msgid "If we want all pixels of all our bands, we'd need to do something like below. Note the differences in this example from previous." msgstr "" -#: ../../en/rasters.rst:514 +#: ../../en/rasters.rst:664 msgid "1. Setting :command:`exclude_nodata_value` to make sure all pixels are returned so that our sets of calls return the same number of rows. The rows out of the function will be naturally in the same order." msgstr "" -#: ../../en/rasters.rst:517 +#: ../../en/rasters.rst:667 msgid "2. Using the `PostgreSQL ROWS FROM constructor `_ , and aliasing each set of columns from our function output with names. So for example the band 1 columns (geom, val, x, y) are renamed to g1, v1, x1, x2" msgstr "" -#: ../../en/rasters.rst:538 +#: ../../en/rasters.rst:688 msgid "We used CROSS JOIN LATERAL in these examples because we wanted to be explicit what we are doing. Since these are all set returning functions, you can replace CROSS JOIN LATERAL with , for short-hand. We'll use a , in the next set of examples" msgstr "" -#: ../../en/rasters.rst:543 +#: ../../en/rasters.rst:694 +msgid "Dumping polygons with ST_DumpAsPolygons" +msgstr "" + +#: ../../en/rasters.rst:696 msgid "Raster also introduces an additional composite type called a :command:`geomval`. Consider a :command:`geomval` as the offspring of a geometry and raster. It contains a geometry and it contains a pixel value." msgstr "" -#: ../../en/rasters.rst:547 +#: ../../en/rasters.rst:700 msgid "You will find several raster functions that return geomvals." msgstr "" -#: ../../en/rasters.rst:549 +#: ../../en/rasters.rst:702 msgid "A commonly used function that outputs geomvals is `ST_DumpAsPolygons `_, which returns a set of contiguous pixels with the same value as a polygon. Again this by default will only check band 1 and exclude no data values unless you override. This example selects only polygons from band 2. You can also apply filters to the values. For most use cases, :command:`ST_DumpAsPolygons` is a better option than :command:`ST_PixelAsPolygons` as it will return far fewer rows." msgstr "" -#: ../../en/rasters.rst:554 +#: ../../en/rasters.rst:707 msgid "This will output 6 rows, and return polygons corresponding to the letters in \"Raster\"." msgstr "" -#: ../../en/rasters.rst:565 +#: ../../en/rasters.rst:718 msgid "Note that it doesn't return a single geometry, because it finds continguous set of pixels with the same value that form a polygon. Even though all these values are the same, they are not continguous." msgstr "" -#: ../../en/rasters.rst:571 +#: ../../en/rasters.rst:724 msgid "A common approach to produce more complex geometries is to group by the values and union." msgstr "" -#: ../../en/rasters.rst:581 +#: ../../en/rasters.rst:734 msgid "This will give you 2 rows back corresponding to the words \"Raster\" and \"Hello\"." msgstr "" -#: ../../en/rasters.rst:585 +#: ../../en/rasters.rst:737 +msgid "Statistics" +msgstr "" + +#: ../../en/rasters.rst:738 +msgid "The most important thing to understand about rasters is that they are statistical tools for storing data in arrays, that you may happen to be able to make look pretty on a screen." +msgstr "" + +#: ../../en/rasters.rst:741 +msgid "You can find a menu of these statistical functions in `Raster Band Statistics `_." +msgstr "" + +#: ../../en/rasters.rst:745 +msgid "ST_SummaryStatsAgg and ST_SummaryStats" +msgstr "" + +#: ../../en/rasters.rst:747 +msgid "Want all stats for a set or rasters, reach for the function `ST_SummaryStatsAgg `_." +msgstr "" + +#: ../../en/rasters.rst:749 +msgid "This query takes about 10 seconds and gives you a summary of the whole table:" +msgstr "" + +#: ../../en/rasters.rst:756 +msgid "Outputs:" +msgstr "" + +#: ../../en/rasters.rst:765 +msgid "Which tells we have a lot of pixels and our max elevation is 411 ft." +msgstr "" + +#: ../../en/rasters.rst:767 +msgid "If you have built overviews, and just need a rough estimate of your mins, maxs, and means use one of your overviews. This next query returns roughly the same values for mins, maxs, and means as the prior but in about 1 second instead of 10." +msgstr "" + +#: ../../en/rasters.rst:776 +msgid "Now armed with this bit of information, we can ask more questions." +msgstr "" + +#: ../../en/rasters.rst:779 +msgid "ST_Histogram" +msgstr "" + +#: ../../en/rasters.rst:781 +msgid "Generally you won't want stats for your whole table, but instead just stats for a particular area, in that case, you'll want to also employ our old friends :command:`ST_Intersects` and :command:`ST_Clip`. If you are also in need of a raster statistics function that doesn't have an aggregate version, you'll want to carry :command:`ST_Union` along for the ride." +msgstr "" + +#: ../../en/rasters.rst:786 +msgid "For this next example we'll use a different stats function `ST_Histogram `_ which has no aggregate equivalent, and for this particular variant, is a set returning function. We are using the same area of interest as some prior examples, but we also need to employ geometry :command:`ST_Transform` to transform our NY state plane meters geometry to our NYC State Plane feet rasters. It is almost always more performant to transform the geometry instead of raster and definitely if your geometry is just a single one." +msgstr "" + +#: ../../en/rasters.rst:803 +msgid "the above query completes in under 60ms and outputs:" +msgstr "" + +#: ../../en/rasters.rst:817 +msgid "Creating Derivative Rasters" +msgstr "" + +#: ../../en/rasters.rst:818 +msgid "PostGIS raster comes packaged with a number of functions for editing rasters. These functions are both used for editing as well as creating derivative raster data sets. You will find these listed in `Raster Editors `_ and `Raster Management `_." +msgstr "" + +#: ../../en/rasters.rst:824 +msgid "Transforming rasters with ST_Transform" +msgstr "" + +#: ../../en/rasters.rst:825 +msgid "Most of our data is in NY State Plane meters (SRID: 26918), however our DEM raster dataset is in NY State Plane feet (SRID: 2263). For the least cumbersome workflow, we need our core datasets to be in the same spatial reference system." +msgstr "" + +#: ../../en/rasters.rst:829 +msgid "The `raster ST_Transform `_ is the function most suited for this job." +msgstr "" + +#: ../../en/rasters.rst:831 +msgid "In order to create a new nyc dem dataset in NY State Plane meters, we'll do the following:" +msgstr "" + +#: ../../en/rasters.rst:841 +msgid "The above on my system took about 1.5 minutes. For a larger data set it would take much longer." +msgstr "" + +#: ../../en/rasters.rst:844 +msgid "The aforementioned examples used two variants of the :command:`ST_Transform` raster function. The first was to get a reference raster that will be used to transform the other raster tiles to guarantee that all tiles have the same alignment. Note the second variant of :command:`ST_Transform` used doesn't even take an input SRID. This is because the SRID and all the pixel scale and block sizes are read from the reference raster. If you used `ST_Transform(rast, srid)` form, then all your rasters might come out with different alignment making it impossible to apply an operation such as :command:`ST_Union` on them." +msgstr "" + +#: ../../en/rasters.rst:851 +msgid "The only problem with the aforementioned :command:`ST_Transform` approach is that when you transform, the transformed often exists in other tiles. If you looked at the above output closely enough by outputting the convex hull of the rasters, in the next example" +msgstr "" + +#: ../../en/rasters.rst:855 +msgid "you'd see annoying overlaps around the borders." +msgstr "" + +#: ../../en/rasters.rst:864 +msgid "viewed in pgAdmin would look something like:" +msgstr "" + +#: ../../en/rasters.rst:870 +msgid "Using ST_MakeEmptyCoverage to create even tiled rasters" +msgstr "" + +#: ../../en/rasters.rst:871 +msgid "A better approach, albeit a bit slower, is to define your own coverage tile structure from scratch using `ST_MakeEmptyCoverage `_ and then find the intersecting tiles for each new tile, and ST_Union these and then use `ST_Transform(ref, ST_Union...)` to create each tile." +msgstr "" + +#: ../../en/rasters.rst:875 +msgid "For this we'll be using quite a few functions, we learned about earlier." +msgstr "" + +#: ../../en/rasters.rst:900 +msgid "Repeating the same exercise as earlier:" +msgstr "" + +#: ../../en/rasters.rst:909 +msgid "viewed in pgAdmin we no longer have overlaps:" +msgstr "" + +#: ../../en/rasters.rst:913 +msgid "On my system this took ~10 minutes and returned 3879 rows. After the creation of the table, we'll want to do the usual of adding a spatial index, primary key, and constraints as follows:" +msgstr "" + +#: ../../en/rasters.rst:928 +msgid "Which should take under 2 minutes for this dataset." +msgstr "" + +#: ../../en/rasters.rst:931 +msgid "Creating overview tables with ST_CreateOverview" +msgstr "" + +#: ../../en/rasters.rst:933 +msgid "Just as with our original dataset, it would be useful to have overview tables to speed up performance of some operations. `ST_CreateOverview `_ is a function fit for that purpose. You can use :command:`ST_CreateOverview` to create overviews also if you neglected to create one during the raster2pgsql load or you decided, you need more overviews." +msgstr "" + +#: ../../en/rasters.rst:939 +msgid "We'll create level 2 and 3 overviews as we had done with our original using this code." +msgstr "" + +#: ../../en/rasters.rst:946 +msgid "This process sadly takes a while, and a longer while the more rows you have so be patient. For this dataset it took about 3-5 minutes for the overview factor `2` and 1 minute for the overview factor `3`." +msgstr "" + +#: ../../en/rasters.rst:949 +msgid "The :command:`ST_CreateOverView` function also adds in the needed constraints so the columns appear with full detail in the `raster_columns` and `raster_overviews` catalogs. It does not add indexes to them though and also does not add an rid column. The rid column is probably not necessary unless you need a primary key to edit with. You would probably want an index which you can create with the following:" +msgstr "" + +#: ../../en/rasters.rst:964 +msgid "ST_CreateOverview has an optional argument for denoting the sampling method. If not specified it uses the default `NearestNeighbor` which is generally the fastest to compute but may not be ideal. Resampling methods is beyond the scope of this workshop." +msgstr "" + +#: ../../en/rasters.rst:970 +msgid "The intersection of rasters and geometries" +msgstr "" + +#: ../../en/rasters.rst:971 +msgid "There are a couple of functions commonly used to compute intersections of rasters and geometries. We've already seen :command:`ST_Clip` in action which returns the intersection of a raster and geometry as a raster, but there are others. For point data, the most commonly used is :command:`ST_Value` and then there is the :command:`ST_Intersection` which has several overloads some returning rasters and some returning a set of `geomval`." +msgstr "" + +#: ../../en/rasters.rst:979 +msgid "Pixel values at a geometric Point" +msgstr "" + +#: ../../en/rasters.rst:981 +msgid "If you need to return values from rasters based on intersection of several ad-hoc geometry points, you'll use `ST_Value `_ or it's nearest relative `ST_NearestValue `_." +msgstr "" + +#: ../../en/rasters.rst:995 +msgid "This example takes about 1 second to return 2444 rows. If you used :command:`ST_Intersects` instead of :command:`&&`, the process would take about 3 seconds. The reason `ST_Intersects` is slower is that it performs an additional recheck in some cases a pixel by pixel check. If you expect all your points to be represented with data in your raster set and your rasters represent a coverage (a continguous set non-overlapping raster tiles), then `&&` is generally a speedier option." +msgstr "" + +#: ../../en/rasters.rst:1000 +msgid "If your raster data is not densely populated or you have overlapping rasters (e.g. they represent different observations in time), or they are skewed (not axis aligned) then there is an advantage to having ST_Intersects weed out the false positives." +msgstr "" + +#: ../../en/rasters.rst:1006 +msgid "ST_Intersection raster style" +msgstr "" + +#: ../../en/rasters.rst:1007 +msgid "Just as you can compute the intersection of two geometries using :command:`ST_Intersection`, you can compute intersection of two rasters or a raster and a geometry using `raster ST_Intersection `_." +msgstr "" + +#: ../../en/rasters.rst:1011 +msgid "What you get out of this beast, are two different kinds of things:" +msgstr "" + +#: ../../en/rasters.rst:1013 +msgid "Intersect a geometry with a raster, and you get a set of `geomval` offspring. Perhaps one, but most often many." +msgstr "" + +#: ../../en/rasters.rst:1016 +msgid "Intersect 2 rasters and you get a single `raster` back." +msgstr "" + +#: ../../en/rasters.rst:1018 +msgid "The golden rule for both raster intersection and geometry intersection is that both parties involved must have the same spatial reference system. For raster/raster, they also have to have same alignment." +msgstr "" + +#: ../../en/rasters.rst:1022 +msgid "Here is an example which answers a question you may have been curious about. If we bucket our elevations into 5 buckets of elevation values, which elevation range results in the most gun fatalities? We know based on our earlier summary statistics that `0` is the lowest value and `411` is the highest value for elevation in our nyc dem dataset, so we use that as min and max value for our `width_bucket `_ call." +msgstr "" + +#: ../../en/rasters.rst:1044 +msgid "Is there an important correlation between gun homicides and elevation? Probably not." +msgstr "" + +#: ../../en/rasters.rst:1048 +msgid "Let's take a look at raster / raster intersection:" +msgstr "" + +#: ../../en/rasters.rst:1057 +msgid "What we get are two rows with NULLLs, and if you have your PostgreSQL set to show notices, you'll see:" +msgstr "" + +#: ../../en/rasters.rst:1059 +msgid "**NOTICE: The two rasters provided do not have the same alignment. Returning NULL**" +msgstr "" + +#: ../../en/rasters.rst:1061 +msgid "In order to fix this, we can align one to the other as it's coming out of the gate using `ST_Resample `_." +msgstr "" + +#: ../../en/rasters.rst:1071 +msgid "Let's also roll it up into a single stats record" +msgstr "" + +#: ../../en/rasters.rst:1083 +msgid "which outputs:" +msgstr "" + +#: ../../en/rasters.rst:1094 msgid "Map Algebra Functions" msgstr "" -#: ../../en/rasters.rst:586 -msgid "Map algebra is the idea that you can do math on your pixel values. The :command:`ST_Union` function covered earlier is a special fast case of map algebra. Then there are the `ST_MapAlgebra `_ family of functions which allow you to define your own crazy math, but at cost of performance." +#: ../../en/rasters.rst:1095 +msgid "Map algebra is the idea that you can do math on your pixel values. The :command:`ST_Union` and :command:`ST_Intersection` functions covered earlier are a special fast case of map algebra. Then there are the `ST_MapAlgebra `_ family of functions which allow you to define your own crazy math, but at cost of performance." msgstr "" -#: ../../en/rasters.rst:592 +#: ../../en/rasters.rst:1103 msgid "People have the habit of jumping to :command:`ST_MapAlgebra`, probably cause the name sounds so cool and sophisticated. Who wouldn't want to tell their friends, \"I'm using a function called ST_MapAlgebra.\" My advice, explore other functions before you jump for that shot-gun. Your life will be simpler and your performance will be 100 times better, and your code will be shorter." msgstr "" -#: ../../en/rasters.rst:598 +#: ../../en/rasters.rst:1109 +msgid "Before we showcase `ST_MapAlgebra`, we'll explore other functions that fit under the `Map Algebra` family of functions and generally have better performance than `ST_MapAlgebra`." +msgstr "" + +#: ../../en/rasters.rst:1113 +msgid "Reclassify your raster using ST_Reclass" +msgstr "" + +#: ../../en/rasters.rst:1115 msgid "An often overlooked map-algebraish function is the `ST_Reclass `_ function, who sits in the background waiting for someone to discover the power and speed it can offer." msgstr "" -#: ../../en/rasters.rst:602 +#: ../../en/rasters.rst:1119 msgid "What does **ST_Reclass** do? It as the name implies, reclassifies your pixel values based on minimalist range algebra." msgstr "" + +#: ../../en/rasters.rst:1121 +msgid "Lets revisit our NYC Dems. Perhaps we only care about classifying our elevations as 1) low, 2) medium, 3) high , and 4) really high. We don't need 411 values, we just need 4. With that said lets do some reclassifying." +msgstr "" + +#: ../../en/rasters.rst:1124 +msgid "The classification scheme is governed by the `reclass expression `_." +msgstr "" + +#: ../../en/rasters.rst:1140 +msgid "Which would output:" +msgstr "" + +#: ../../en/rasters.rst:1152 +msgid "If this were a classification scheme we preferred, we could create a new table using the ST_Reclass to recompute each tile." +msgstr "" + +#: ../../en/rasters.rst:1155 +msgid "Coloring your rasters with ST_ColorMap" +msgstr "" + +#: ../../en/rasters.rst:1156 +msgid "The `ST_ColorMap `_ function is another mapalgebraish function that reclassifies your pixel values. Except it is band creating. It converts a single band raster such as our Dems into a visually presentable 3 or 4 banded raster." +msgstr "" + +#: ../../en/rasters.rst:1160 +msgid "You could use one of the built-in colormaps as below if you don't want to fuss with creating one." +msgstr "" + +#: ../../en/rasters.rst:1171 +msgid "Which looks like:" +msgstr "" + +#: ../../en/rasters.rst:1175 +msgid "The bluer the color the lower the elevation and the redder the color the higher the elevation." +msgstr "" diff --git a/postgis-intro/sources/locale/ko/LC_MESSAGES/rasters.po b/postgis-intro/sources/locale/ko/LC_MESSAGES/rasters.po index 376b773e..17cd270b 100644 --- a/postgis-intro/sources/locale/ko/LC_MESSAGES/rasters.po +++ b/postgis-intro/sources/locale/ko/LC_MESSAGES/rasters.po @@ -9,7 +9,7 @@ msgid "" msgstr "" "Project-Id-Version: Introduction to PostGIS 1.1\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2023-01-13 00:30-0500\n" +"POT-Creation-Date: 2023-01-25 04:15-0500\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" @@ -31,378 +31,826 @@ msgstr "" msgid "Although pretty pictures such as those you see on your TV screen are rasters, rasters may not be that exciting to look at. In a nutshell, a raster is a matrix, pinned on a coordinate system, that has values that can represent anything you want them to represent." msgstr "" -#: ../../en/rasters.rst:15 -msgid "Since rasters live in cartesian space, rasters can interact with geometries. PostGIS offers many functions that take as input both rasters and geometries. Also many operations applied to rasters will result in geometries. Common ones are the `ST_Polygon`, `ST_Envelope`, `ST_ConvexHull`, and `ST_MinConvexHull` as shown below." +#: ../../en/rasters.rst:17 +msgid "Since rasters live in cartesian space, rasters can interact with geometries. PostGIS offers many functions that take as input both rasters and geometries. Many operations applied to rasters will result in geometries. Common ones are the `ST_Polygon`, `ST_Envelope`, `ST_ConvexHull`, and `ST_MinConvexHull` as shown below. When you cast a raster to a geometry, what is output is the `ST_ConvexHull` of the raster." msgstr "" -#: ../../en/rasters.rst:21 -msgid "The raster format is commonly used to store elevation data, temperature data, satellite data, and thematic data representing things like environmental contamination, population density, and environmental hazard occurrences." +#: ../../en/rasters.rst:24 +msgid "The raster format is commonly used to store elevation data, temperature data, satellite data, and thematic data representing things like environmental contamination, population density, and environmental hazard occurrences. You can use rasters to store any numeric data that has a meaningful coordinate location. The only restriction is that for all data in a specific band the numeric data types have to be the same." msgstr "" -#: ../../en/rasters.rst:23 -msgid "Although raster data can be created from scratch in PostGIS, a more common approach is to load raster data from various formats using the `raster2pgsql `_ command line tool packaged with PostGIS. Before all of that, you must enable raster support in your database by running the command:" +#: ../../en/rasters.rst:28 +msgid "Although raster data can be created from scratch in PostGIS, a more common approach is to load raster data from various formats using the :command:`raster2pgsql` command line tool packaged with PostGIS. Before all of that, you must enable raster support in your database by running the command:" msgstr "" -#: ../../en/rasters.rst:30 +#: ../../en/rasters.rst:37 msgid "Creating Rasters From Geometries" msgstr "" -#: ../../en/rasters.rst:31 +#: ../../en/rasters.rst:38 msgid "We'll start off by first creating raster data from vector data, and then move on to the more exciting approach of loading data from a raster source. You will find that raster data is available in abundance and often free from various government sites." msgstr "" -#: ../../en/rasters.rst:34 +#: ../../en/rasters.rst:41 msgid "We'll start by converting some geometries into rasters using `ST_AsRaster `_ function as follows." msgstr "" -#: ../../en/rasters.rst:48 -msgid "The above example CREATEs a table (**rasters**) from geometries formed from letters using the PostGIS 3.2+ `ST_Letters `_ function. Rasters similar to geometries, can take advantage of spatial indexes. The spatial index used for raster is a functional index that indexes the geometry convexhull of the raster. When loading data with :command:`raster2pgsql` with the :command:`I` switch, the :command:`CREATE INDEX` step is done for you." +#: ../../en/rasters.rst:55 +msgid "The above example CREATEs a table (**rasters**) from geometries formed from letters using the PostGIS 3.2+ `ST_Letters `_ function. Rasters similar to geometries, can take advantage of spatial indexes. The spatial index used for raster is a functional index that indexes the geometry convexhull of the raster." msgstr "" -#: ../../en/rasters.rst:53 -msgid "You can see some useful metadata of your rasters with the following query which utilizes the postgis raster functions `ST_Count `_ function to count the number of pixels that have data and the `ST_MetaData `_ function to provide all sorts of useful background info for our rasters." +#: ../../en/rasters.rst:58 +msgid "You can see some useful metadata of your rasters with the following query which utilizes the postgis raster `ST_Count `_ function to count the number of pixels that have data and the `ST_MetaData `_ function to provide all sorts of useful background info for our rasters." msgstr "" -#: ../../en/rasters.rst:71 -msgid "There are two levels of raster functions. There are functions such as ST_MetaData that work at the raster level and there are functions such as :command:`ST_Count` function and :command:`ST_BandMetaData `_ function that work at the band level. Most functions in postgis raster that work at the band level, work with only one band at a time, and assume the band you want is `1`." +#: ../../en/rasters.rst:76 +msgid "There are two levels of raster functions. There are functions such as ST_MetaData that work at the raster level and there are functions such as :command:`ST_Count` function and `ST_BandMetaData `_ function that work at the band level. Most functions in postgis raster that work at the band level, work with only one band at a time, and assume the band you want is `1`." msgstr "" -#: ../../en/rasters.rst:78 +#: ../../en/rasters.rst:83 +msgid "If you have a multi-band raster, and you need to count the pixel not no-data values in a band other than 1, you would explicitly specify the band number as follows `ST_Count(rast,2)`." +msgstr "" + +#: ../../en/rasters.rst:85 msgid "Note how all the rasters have a 150x150 dimension. This is not ideal. This means that in order to force that, our rasters, are squished in all sorts of ways. If only we could see the ugliness of the rasters before us." msgstr "" -#: ../../en/rasters.rst:81 -msgid "If you have a multi-band raster, and you need to count the pixel not no-data values in a band other than 1, you would explicitly specify the band number as follows `ST_Count(rast,2)`." +#: ../../en/rasters.rst:89 +msgid "Loading Rasters using raster2pgsql" msgstr "" -#: ../../en/rasters.rst:85 +#: ../../en/rasters.rst:90 +msgid "`raster2pgsql `_ is a command-line tool often packaged with PostGIS. If you are on windows and used application stackbuilder PostGIS Bundle, you'll find :command:`raster2pgsql.exe` in the folder ``C:\\Program Files\\PostgreSQL\\15\\bin`` where the *15* should be replaced with the version of PostgreSQL you are running." +msgstr "" + +#: ../../en/rasters.rst:93 +msgid "If you are using Postgres.App, you'll find raster2pgsql among the other `Postgres.app CLI Tools `_." +msgstr "" + +#: ../../en/rasters.rst:95 +msgid "On Ubuntu and Debian, you will need" +msgstr "" + +#: ../../en/rasters.rst:101 +msgid "to have the PostGIS commandline tools installed. This may install an additional version of PostgreSQL as well. You can see a list of clusters in Debian/Ubuntu using the :command:`pg_lsclusters` command and drop them using the :command:`pg_dropcluster` command." +msgstr "" + +#: ../../en/rasters.rst:106 +msgid "For this and later exercises, we'll be using `nyc_dem.tif` found in the file `PG Raster Workshop Dataset https://postgis.net/stuff/workshop-data/postgis_raster_workshop.zip `_. For some geometry/raster examples, we will also be using NYC data loaded from prior chapters. In-lieu of loading the tif, you can restore the `nyc_dem.backup` included in the zip file in your database using the :command:`pg_restore` commandline tool or the pgAdmin **Restore** menu." +msgstr "" + +#: ../../en/rasters.rst:112 +msgid "This raster data was sourced from `NYC DEM 1-foot Integer `_ which is a 3GB DEM tif representing elevation relative to sea level with buildings and overwater removed. We then created a lower res version of it." +msgstr "" + +#: ../../en/rasters.rst:115 +msgid "The :command:`rasterpgsql` tool is similar to the :command:`shp2gpsql` except instead of loading ESRI shapefiles into PostGIS geometry/geography tables, it loads any GDAL supported raster format into raster tables. Just like :command:`shp2pgsql` you can pass it a spatial reference id (SRID) of the source. Unlike :command:`shp2pgsql` it can infer the spatial references system of the source data if your source data has suitable metadata." +msgstr "" + +#: ../../en/rasters.rst:119 +msgid "For a full exposure of all the possible switches offered refer to `raster2pgsql options `_." +msgstr "" + +#: ../../en/rasters.rst:121 +msgid "Some other notable options :command:`raster2pgsql` offers which we will not cover are:" +msgstr "" + +#: ../../en/rasters.rst:123 +msgid "Ability to denote the SRID of the source. Instead, we'll rely on raster2pgsql guessing skills." +msgstr "" + +#: ../../en/rasters.rst:124 +msgid "Ability to set the `nodata` value, when not specified, raster2pgsql tries to infer from the file." +msgstr "" + +#: ../../en/rasters.rst:125 +msgid "Abiliity to load out-of-database rasters." +msgstr "" + +#: ../../en/rasters.rst:127 +msgid "To load all the tif files in our folder and also create overviews, we would run the below." +msgstr "" + +#: ../../en/rasters.rst:133 +msgid "-d to drop the tables if they already exist" +msgstr "" + +#: ../../en/rasters.rst:134 +msgid "The above command uses `-e` to do load immediately instead of committing in a transaction" +msgstr "" + +#: ../../en/rasters.rst:135 +msgid "`-C` set raster constraints, this is useful for `raster_columns` to show info. You may want to combine with `-x` to exclude the extent constraint, which is a slow constraint to check and also hampers future loads in the table." +msgstr "" + +#: ../../en/rasters.rst:138 +msgid "`-M` to vacuum and analyze after load, to improve query planner statistics" +msgstr "" + +#: ../../en/rasters.rst:139 +msgid "`-Y` to use copy in batches of 50. If you are running PostGIS 3.3 or higher, you can use `-Y 1000` to have copy be in batches of 1000, or even higher number. This will run faster, but will use more memory." +msgstr "" + +#: ../../en/rasters.rst:141 +msgid "`-l 2,3` to create over view tables: `o_2_ncy_dem` and `o_3_nyc_dem`. This is useful for viewing data." +msgstr "" + +#: ../../en/rasters.rst:142 +msgid "-I to create a spatial index" +msgstr "" + +#: ../../en/rasters.rst:143 +msgid "`-F` to add file name, if you have only one tif file, this is kinda pointless. If you had multiple, this would be useful to tell you what file each row came from." +msgstr "" + +#: ../../en/rasters.rst:145 +msgid "`-t` to set the block size. Note if you are not sure the best size use, use `-t auto` instead and raster2pgql will use the same tiling as what was in the tif. The output will tell you what the blocksize is it chose. Cancel if it looks huge or weird. The original file had a size of 300x7 which is not ideal." +msgstr "" + +#: ../../en/rasters.rst:149 +msgid "Use :command:`psql` to run the generated sql against the database. If you want to dump to a file instead, use `> nyc_dem.sql`" +msgstr "" + +#: ../../en/rasters.rst:153 +msgid "For this example, we have only one tif file, so we could instead specify the full file name, instead of `*.tif`. If the files are not in your current directory, you can also specify a folder path with `*.tif`." +msgstr "" + +#: ../../en/rasters.rst:158 +msgid "If you are on windows and need to reference the folder, make sure to include the drive letter such as `C:/workshop/*.tif`" +msgstr "" + +#: ../../en/rasters.rst:161 +msgid "You'll often hear in PostGIS lingo, the term **raster tile** and **raster** used somewhat interchangeably. A raster tile really corresponds to a particular raster in a raster column which is a subset of a bigger raster, such as this NYC dem data we just loaded. This is because when rasters are loaded into PostGIS from big raster files, they chopped into many rows to make them manageable. Each raster in each row then is a part of a bigger raster. Each tile covers same size area denoted by the blocksize you specified. Rasters are sadly limited by the 1GB PostgreSQL `TOAST `_ limit and also the slow process of detoasting and so we need to chop up in order to achieve decent performance or to even store them." +msgstr "" + +#: ../../en/rasters.rst:170 msgid "Viewing Rasters in Browser" msgstr "" -#: ../../en/rasters.rst:86 -msgid "Although pgAdmin and psql have no mechanism yet to view postgis rasters, we have a couple of options. For smallish rasters the easiest is to output to a web-friendly raster format such as PNG using batteries included postgis raster functions like `ST_AsPNG` or `ST_AsGDALRaster` listed in `PostGIS Raster output functions `_. As your rasters get larger, you'll want to graduate to a tool such as QGIS to view them in all their glory or the GDAL family of commandline tools such as gdal_translate to export them to other raster formats. Remember though, postgis rasters are built for analysis, not for generating pretty pictures for you to look at." +#: ../../en/rasters.rst:171 +msgid "Although pgAdmin and psql have no mechanism yet to view postgis rasters, we have a couple of options. For smallish rasters the easiest is to output to a web-friendly raster format such as PNG using batteries included postgis raster functions like `ST_AsPNG` or `ST_AsGDALRaster` listed in `PostGIS Raster output functions `_. As your rasters get larger, you'll want to graduate to a tool such as QGIS to view them in all their glory or the GDAL family of commandline tools such as :command:`gdal_translate` to export them to other raster formats. Remember though, postgis rasters are built for analysis, not for generating pretty pictures for you to look at." msgstr "" -#: ../../en/rasters.rst:93 +#: ../../en/rasters.rst:178 msgid "One caveat, by default all different raster types outputs are disabled. In order to utilize these, you'll need to enable drivers, all or a subset as detailed in `Enable GDAL Raster drivers `_" msgstr "" -#: ../../en/rasters.rst:101 +#: ../../en/rasters.rst:186 msgid "If you don't want to have to do this for each connection, you can set at the database level using:" msgstr "" -#: ../../en/rasters.rst:107 +#: ../../en/rasters.rst:192 msgid "Each new connection to the database will use that setting." msgstr "" -#: ../../en/rasters.rst:109 +#: ../../en/rasters.rst:194 msgid "Run the below query and copy and paste the output into the address bar of your web browser." msgstr "" -#: ../../en/rasters.rst:120 +#: ../../en/rasters.rst:205 msgid "For the rasters created thus far, we didn't specify the number of bands nor did we even define their relation to earth. As such our rasters have an unknown spatial reference system (0)." msgstr "" -#: ../../en/rasters.rst:123 +#: ../../en/rasters.rst:208 msgid "You can think of a rasters exoskeletal as a geometry. A matrix encased in a geometric envelop. In order to do useful analysis, we need to georeference our rasters, meaning we want each pixel (rectangle) to represent some meaningful plot of space." msgstr "" -#: ../../en/rasters.rst:128 +#: ../../en/rasters.rst:213 msgid "The `ST_AsRaster` has many overloaded representations. The earlier example used the simplest such implementation and accepted the default arguments which are 8BUI and 1 band, with no data being 0. If you need to use the other variants, you should use the named arguments call syntax so that you don't accidentally fall into the wrong variant of the function or get **function is not unique** errors." msgstr "" -#: ../../en/rasters.rst:133 -msgid "If you start with a geometry that has a spatial reference system, you'll end up with a raster with same spatial reference system. In this next example, we'll plop our words in New York in bright cheery colors. We will also use pixel scale instead of width and height so that our raster pixel sizes represent 1 meter x 1 meter of space." +#: ../../en/rasters.rst:221 +msgid "If you start with a geometry that has a spatial reference system, you'll end up with a raster with same spatial reference system. In this next example, we'll plop our words in New York in bright cheery colors. We will also use pixel scale instead of width and height so that our raster pixel sizes represent 1 meter x 1 meter of space." msgstr "" -#: ../../en/rasters.rst:155 +#: ../../en/rasters.rst:244 msgid "If we then look at this, we'll see a non-squashed colored geometry." msgstr "" -#: ../../en/rasters.rst:166 +#: ../../en/rasters.rst:255 msgid "Repeat for Raster:" msgstr "" -#: ../../en/rasters.rst:177 +#: ../../en/rasters.rst:266 msgid "What is more telling, if we rerun the" msgstr "" -#: ../../en/rasters.rst:184 +#: ../../en/rasters.rst:273 msgid "Observe the metadata of the New York entries. They have the New York state plane meter spatial reference system. They also have the same scale. Since each unit is 1x1 meter, the width of the word **Raster** is now wider than **Hello**." msgstr "" -#: ../../en/rasters.rst:199 +#: ../../en/rasters.rst:288 msgid "Raster Spatial Catalog tables" msgstr "" -#: ../../en/rasters.rst:200 -msgid "Similar to the geometry and geography types, raster has a set of catalogs that show you all raster columns in your database. These are `raster_columns and raster_overviews `_. Both of these are views similar to the `geometry_columns` and `geography_columns`." +#: ../../en/rasters.rst:289 +msgid "Similar to the geometry and geography types, raster has a set of catalogs that show you all raster columns in your database. These are `raster_columns and raster_overviews `_." msgstr "" -#: ../../en/rasters.rst:210 +#: ../../en/rasters.rst:295 +msgid "raster_columns" +msgstr "" + +#: ../../en/rasters.rst:297 +msgid "The `raster_columns` view to the sibling to the `geometry_columns` and `geography_columns`, providing much the same data and more, but for raster columns." +msgstr "" + +#: ../../en/rasters.rst:305 msgid "Explore the table, and you'll find this:" msgstr "" -#: ../../en/rasters.rst:219 -msgid "a very disappointing row of largely unfilled information." +#: ../../en/rasters.rst:317 +msgid "a disappointing row of largely unfilled information for the `rasters` table." msgstr "" -#: ../../en/rasters.rst:221 +#: ../../en/rasters.rst:319 msgid "Unlike geometry and geography, raster does not support type modifiers, because type modifier space is too limited and there are more critical properties than what can fit in a type modifier." msgstr "" -#: ../../en/rasters.rst:224 -msgid "Raster instead relies on constraints, and reads these constraints back as part of the view. So let's try to add some constraints to our table." +#: ../../en/rasters.rst:322 +msgid "Raster instead relies on constraints, and reads these constraints back as part of the view." +msgstr "" + +#: ../../en/rasters.rst:324 +msgid "Look at the other rows from the tables we loaded using :command:`raster2pgsql`. Because we used the `-C` switch :command:`raster2pgsql` added constraints for the srid and other info it was able to read from the tif or that we passed in. The overview tables generated with the `-l` switch `o_2_nyc_dem` and `o_3_nyc_dem` show up as well." msgstr "" -#: ../../en/rasters.rst:232 -msgid "And you'll be bombarded with a whole bunch of notices about how your raster data is mess and nothing can be constrained. If you look at raster_columns again, still the same disappointing story of many blank rows." +#: ../../en/rasters.rst:327 +msgid "Let's try to add some constraints to our table." msgstr "" -#: ../../en/rasters.rst:236 +#: ../../en/rasters.rst:334 +msgid "And you'll be bombarded with a whole bunch of notices about how your raster data is a mess and nothing can be constrained. If you look at raster_columns again, still the same disappointing story of many blank rows for `rasters`." +msgstr "" + +#: ../../en/rasters.rst:338 msgid "In order for constraints to be applied, all rasters in your table must be constrainable by at least one rule." msgstr "" -#: ../../en/rasters.rst:239 +#: ../../en/rasters.rst:341 msgid "We can perhaps do this, let's just lie and say all our data is in New York State plane." msgstr "" -#: ../../en/rasters.rst:252 +#: ../../en/rasters.rst:355 msgid "Ah progress:" msgstr "" -#: ../../en/rasters.rst:261 +#: ../../en/rasters.rst:364 msgid "The more you can constrain all your rasters, the more columns you'll see filled in and also the more operations you'll be able to do across all the tiles in your raster. Keep in mind that in some cases, you may not want to apply all constraints." msgstr "" -#: ../../en/rasters.rst:265 +#: ../../en/rasters.rst:368 msgid "For example, if you plan to load more data into your raster table, you'll want to skip the extent constraint since that would require that all rasters are within the extent of the extent constraint." msgstr "" -#: ../../en/rasters.rst:269 -msgid "You'll often here in PostGIS lingo, the term **raster tile** and **raster** used somewhat interchangeably. A raster tile really corresponds to a particular raster in a raster column which is a subset of a bigger raster. This is because when rasters are loaded into PostGIS from big raster files, they are often chopped up to make them manageable." +#: ../../en/rasters.rst:373 +msgid "raster_overviews" +msgstr "" + +#: ../../en/rasters.rst:374 +msgid "Raster overview columns appear both in the `raster_columns` meta catalog and another meta catalog called `raster_overviews`. Overviews are used mostly to speed up viewing at higher zoom levels. They can also be used for quick back of the envelop analysis, providing less accurate stats, but at a much faster speed than applying to the raw raster table." +msgstr "" + +#: ../../en/rasters.rst:379 +msgid "To inspect the overviews, run:" msgstr "" -#: ../../en/rasters.rst:275 -msgid "Exploring Raster Functions" +#: ../../en/rasters.rst:386 +msgid "and you'll see the output:" msgstr "" -#: ../../en/rasters.rst:276 -msgid "The :command:`postgis_raster` extension has over 100 functions to choose from. We'll focus on the ones you will commonly use. PostGIS raster functionality was patterned after the PostGIS geometry support. As such you'll find an overlap of functions between raster and geometry where it makes sense. Common ones you'll use that have equivalent in geometry world are :command:`ST_Intersects`, :command:`ST_SetSRID`, :command:`ST_SRID`, :command:`ST_Union`, :command:`ST_Intersection`, and :command:`ST_Transform`. In addition to those overlapping functions, it offers many functions that work in conjunction with geometry or are very specific to rasters." +#: ../../en/rasters.rst:396 +msgid "The `raster_overviews` table only provides you the overview_factor and the name of the parent table. All this information is something you could have figured out yourself by the `raster2pgsql` naming convention for overviews." msgstr "" -#: ../../en/rasters.rst:285 -msgid "Unioning Rasters" +#: ../../en/rasters.rst:400 +msgid "The `overview_factor` tells you at what resolution the row is with respect to it's parent. An `overview_factor` of `2` means that 2x2 = 4 tiles can fit into one overview_2 tile. Similarly an overview_factor of `1` meants that 2x2x2 = 8 tiles of the original can be shoved into an overview_3 tile." msgstr "" -#: ../../en/rasters.rst:286 +#: ../../en/rasters.rst:407 +msgid "Common Raster Functions" +msgstr "" + +#: ../../en/rasters.rst:408 +msgid "The :command:`postgis_raster` extension has over 100 functions to choose from. PostGIS raster functionality was patterned after the PostGIS geometry support. You'll find an overlap of functions between raster and geometry where it makes sense. Common ones you'll use that have equivalent in geometry world are :command:`ST_Intersects`, :command:`ST_SetSRID`, :command:`ST_SRID`, :command:`ST_Union`, :command:`ST_Intersection`, and :command:`ST_Transform`." +msgstr "" + +#: ../../en/rasters.rst:415 +msgid "In addition to those overlapping functions, it supports the `&&` overlap operator between rasters and between a raster and geometry. It also offers many functions that work in conjunction with geometry or are very specific to rasters." +msgstr "" + +#: ../../en/rasters.rst:419 +msgid "You need a function like :command:`ST_Union` to reconstitute a region. Because performance gets slow, the more pixels a function needs to analyse, you need a fast acting function :command:`ST_Clip` to clip the rasters to just the portions of interest for your analysis." +msgstr "" + +#: ../../en/rasters.rst:423 +msgid "Finally you need :command:`ST_Intersects` or :command:`&&` to zoom in on the raster tiles that contain your areas of interest. The `&&` operator, is a faster process than the `ST_Intersects`. Both can take advantage of raster spatial indexes. We'll cover these bread and butter functions first before moving on to other sections where we will use them in concert with other raster and geometry functions." +msgstr "" + +#: ../../en/rasters.rst:429 +msgid "Unioning Rasters with ST_Union" +msgstr "" + +#: ../../en/rasters.rst:430 msgid "The `ST_Union `_ function for raster, just as the geometry equivalent :command:`ST_Union`, aggregates a set of rasters together into a single raster. However, just as with geometry, not all rasters can be combined together, but the rules for raster unioning are more complicated than geometry rules. In the case of geometries, all you need is to have the same spatial reference system, but for rasters that is not sufficient." msgstr "" -#: ../../en/rasters.rst:294 -msgid "If you were to attempt, the following" +#: ../../en/rasters.rst:438 +msgid "If you were to attempt, the following:" msgstr "" -#: ../../en/rasters.rst:301 +#: ../../en/rasters.rst:445 msgid "You'd be summarily punished with an error:" msgstr "" -#: ../../en/rasters.rst:303 +#: ../../en/rasters.rst:447 msgid "**ERROR: rt_raster_from_two_rasters: The two rasters provided do not have the same alignment SQL state: XX000**" msgstr "" -#: ../../en/rasters.rst:306 +#: ../../en/rasters.rst:450 msgid "What is this same alignment thing, that is preventing you from unioning your precious rasters?" msgstr "" -#: ../../en/rasters.rst:308 +#: ../../en/rasters.rst:452 msgid "In order for rasters to be combined, they need to be on the same grid so to speak. Meaning they must have same pixel sizes, same orientation (the skew), same spatial reference system, and their pixels must not cut into each other, meaning they share the same worldly pixel grid." msgstr "" -#: ../../en/rasters.rst:312 +#: ../../en/rasters.rst:456 msgid "If you try the same query, but just with words we carefully placed in New York." msgstr "" -#: ../../en/rasters.rst:314 +#: ../../en/rasters.rst:458 msgid "Again, the same error. These are the same spatial ref system, the same pixel sizes, and yet it's still not good enough. Because their grids are off." msgstr "" -#: ../../en/rasters.rst:318 +#: ../../en/rasters.rst:462 msgid "We can fix this by shifting the upper left y coordinates ever so slightly and then trying again. If our grids start at integer level since our pixel sizes are whole integer, then the pixels won't cut into each other." msgstr "" -#: ../../en/rasters.rst:333 ../../en/rasters.rst:382 +#: ../../en/rasters.rst:477 ../../en/rasters.rst:526 msgid "Voila it worked, and if we were to view, we'd see something like this:" msgstr "" -#: ../../en/rasters.rst:339 +#: ../../en/rasters.rst:483 msgid "If ever you are unclear why your rasters don't have the same alignment, you can use the function `ST_SameAlignment `_, which will compare 2 rasters or a set of rasters and tell you if they have the same alignment. If you have notices enabled, the NOTICE will tell you what is off with the rasters in question. The `ST_NotSameAlignmentReason `_, instead of just a notice will output the reason. It however only works with two rasters at a time." msgstr "" -#: ../../en/rasters.rst:346 +#: ../../en/rasters.rst:490 msgid "One major way in which the `ST_Union(raster) `_ raster function deviates from the `ST_Union(geometry) `_ geometry function is that it allows for an argument called *uniontype*. This argument by default is set to `LAST` if you don't specify it, which means, take the **LAST** raster pixel values in occasions where the raster pixel values overlap. As a general rule, pixels in a band that are marked as no-data are ignored." msgstr "" -#: ../../en/rasters.rst:352 +#: ../../en/rasters.rst:496 msgid "Just as with most aggregates in PostgreSQL, you can put a :command:`ORDER BY` clause as part of the function call as is done in the prior example. Specifying the order, allows you to control which raster takes priority. So in our prior example, *Raster* trumped *Hello* because *Raster* is alphabetically last." msgstr "" -#: ../../en/rasters.rst:356 +#: ../../en/rasters.rst:500 msgid "Observe, if you switch the order:" msgstr "" -#: ../../en/rasters.rst:366 +#: ../../en/rasters.rst:510 msgid "Then *Hello* trumps *Raster* because Hello is now the last overlaid." msgstr "" -#: ../../en/rasters.rst:368 +#: ../../en/rasters.rst:512 msgid "The :command:`FIRST` union type is the reverse of :command:`LAST`." msgstr "" -#: ../../en/rasters.rst:370 +#: ../../en/rasters.rst:514 msgid "But on occassion, **LAST** may not be the right operation. Let's suppose our rasters represented two different sets of observations from two different devices. These devices measure the same thing, and we aren't sure which is right when they cross paths, so we'd instead like to take the `MEAN` of the results. We'd do this:" msgstr "" -#: ../../en/rasters.rst:386 +#: ../../en/rasters.rst:530 msgid "So instead of trumping, we have a blending of the two forces. In the case of :command:`MEAN` union type, there is no point in specifying order, because the result would be the average of overlapping pixel values." msgstr "" -#: ../../en/rasters.rst:390 +#: ../../en/rasters.rst:534 msgid "Note that for geometries since geometries are vector and thus have no values besides there or not there, there really isn't any ambiguity on how to combine two vectors when they intersect." msgstr "" -#: ../../en/rasters.rst:394 +#: ../../en/rasters.rst:538 msgid "Another feature of the raster :command:`ST_Union` we glossed over, is this idea of if you should return all bands or just some bands. When you don't specify what bands to union, :command:`ST_Union` will combine same banded numbers and use the :command:`LAST` unioning strategy. If you have multiple bands, this may not be what you want to do. Perhaps you only want to union, the second band. In this case, the Green Band and you want the count of pixel values." msgstr "" -#: ../../en/rasters.rst:415 +#: ../../en/rasters.rst:559 msgid "Note in the case of the **COUNT** union type, which counts the number of pixels filled in and returns that value, the result is always a **32BUI** similar to how when you do a :command:`COUNT` in sql, the result is always a bigint, to accommodate large counts." msgstr "" -#: ../../en/rasters.rst:419 +#: ../../en/rasters.rst:563 msgid "In other cases, the band pixel type does not change and is set to the max value or rounded if the amounts exceed the bounds of the type. Why would anyone ever want to count pixels that intersect at a location. Well suppose each of your rasters represent police squadrons and incidents of arrests in the areas. Each value, might represent a different kind of arrest reason. You are doing stats on how many arrests in each region, therefore you only care about the count of arrests." msgstr "" -#: ../../en/rasters.rst:428 +#: ../../en/rasters.rst:572 msgid "Or perhaps, you want to do all bands, but you want different strategies." msgstr "" -#: ../../en/rasters.rst:438 +#: ../../en/rasters.rst:582 msgid "Using the *unionarg[]* variant of the :command:`ST_Union` function, also allows you to shuffle the order of the bands." msgstr "" -#: ../../en/rasters.rst:441 -msgid "Clipping Rasters" +#: ../../en/rasters.rst:585 +msgid "Clipping Rasters with help of ST_Intersects" msgstr "" -#: ../../en/rasters.rst:442 +#: ../../en/rasters.rst:586 msgid "The `ST_Clip `_ function is one of the most widely used functions for PostGIS rasters. The main reason is the more pixels you need to inspect or do operations on, the slower your processing. **ST_Clip** clips your raster to just the area of interest, so you can isolate your operations to just that area." msgstr "" -#: ../../en/rasters.rst:446 +#: ../../en/rasters.rst:590 msgid "This function is also special in that it utilizes the power of geometry to help raster analysis. To reduce the number of pixels, :command:`ST_Union` has to handle, each raster is clipped first to the area we are interested in." msgstr "" -#: ../../en/rasters.rst:458 -msgid "This example showcases several functions working in unison. The :command:`ST_Intersects` function employed is the one packaged with **postgis_raster** and can intersect 2 rasters or a raster and a geometry. Similar to the geometry :command:`ST_Intersects` the raster :command:`ST_Intersects` can take advantage of spatial indexes on the raster or geometry tables." +#: ../../en/rasters.rst:602 +msgid "This example showcases several functions working in unison. The :command:`ST_Intersects` function employed is the one packaged with **postgis_raster** and can intersect 2 rasters or a raster and a geometry. Similar to the geometry :command:`ST_Intersects` the `raster ST_Intersects `_ can take advantage of spatial indexes on the raster or geometry tables." msgstr "" -#: ../../en/rasters.rst:464 +#: ../../en/rasters.rst:609 msgid "Converting Rasters to Geometries" msgstr "" -#: ../../en/rasters.rst:465 -msgid "Rasters can just as easily be morphed into geometries. Lets start with our prior example, but convert it to a polygon using `ST_Polygon `_ function." +#: ../../en/rasters.rst:610 +msgid "Rasters can just as easily be morphed into geometries." +msgstr "" + +#: ../../en/rasters.rst:613 +msgid "The polygon of a raster with ST_Polygon" +msgstr "" + +#: ../../en/rasters.rst:614 +msgid "Lets start with our prior example, but convert it to a polygon using `ST_Polygon `_ function." msgstr "" -#: ../../en/rasters.rst:477 +#: ../../en/rasters.rst:625 msgid "If you click on the geometry viewer in pgAdmin, you can see this in all it's glory without any hacks." msgstr "" -#: ../../en/rasters.rst:481 -msgid "ST_Polygon considers all the pixels that have values (not no-data) in a particular band, and converts them to geometry. Like many other functions in raster, ST_Polygon only considers 1 band. If no band is specified, it will consider only the first band." +#: ../../en/rasters.rst:629 +msgid ":command:`ST_Polygon` considers all the pixels that have values (not no-data) in a particular band, and converts them to geometry. Like many other functions in raster, :command:`ST_Polygon` only considers 1 band. If no band is specified, it will consider only the first band." +msgstr "" + +#: ../../en/rasters.rst:634 +msgid "The pixel rectangles of a raster with ST_PixelAsPolygons" msgstr "" -#: ../../en/rasters.rst:485 +#: ../../en/rasters.rst:635 msgid "Another popularly used function is the `ST_PixelAsPolygons `_ function. You should rarely use :command:`ST_PixelAsPolygons` on a large raster without first clipping because you will end up with millions of rows, one for each pixel." msgstr "" -#: ../../en/rasters.rst:488 +#: ../../en/rasters.rst:638 msgid ":command:`ST_PixelAsPolygons` returns a table consisting of geom, val, x, and y. Where x is the column number, and y is the row number in the raster." msgstr "" -#: ../../en/rasters.rst:491 +#: ../../en/rasters.rst:641 msgid ":command:`ST_PixelAsPolygons` similar to other raster functions works on one band at a time and works on band 1 if no band is specified. It also by default returns only pixels that have values." msgstr "" -#: ../../en/rasters.rst:503 +#: ../../en/rasters.rst:653 msgid "Which outputs:" msgstr "" -#: ../../en/rasters.rst:507 +#: ../../en/rasters.rst:657 msgid "and if we inspect using the geometry viewer, we'd see:" msgstr "" -#: ../../en/rasters.rst:511 +#: ../../en/rasters.rst:661 msgid "If we want all pixels of all our bands, we'd need to do something like below. Note the differences in this example from previous." msgstr "" -#: ../../en/rasters.rst:514 +#: ../../en/rasters.rst:664 msgid "1. Setting :command:`exclude_nodata_value` to make sure all pixels are returned so that our sets of calls return the same number of rows. The rows out of the function will be naturally in the same order." msgstr "" -#: ../../en/rasters.rst:517 +#: ../../en/rasters.rst:667 msgid "2. Using the `PostgreSQL ROWS FROM constructor `_ , and aliasing each set of columns from our function output with names. So for example the band 1 columns (geom, val, x, y) are renamed to g1, v1, x1, x2" msgstr "" -#: ../../en/rasters.rst:538 +#: ../../en/rasters.rst:688 msgid "We used CROSS JOIN LATERAL in these examples because we wanted to be explicit what we are doing. Since these are all set returning functions, you can replace CROSS JOIN LATERAL with , for short-hand. We'll use a , in the next set of examples" msgstr "" -#: ../../en/rasters.rst:543 +#: ../../en/rasters.rst:694 +msgid "Dumping polygons with ST_DumpAsPolygons" +msgstr "" + +#: ../../en/rasters.rst:696 msgid "Raster also introduces an additional composite type called a :command:`geomval`. Consider a :command:`geomval` as the offspring of a geometry and raster. It contains a geometry and it contains a pixel value." msgstr "" -#: ../../en/rasters.rst:547 +#: ../../en/rasters.rst:700 msgid "You will find several raster functions that return geomvals." msgstr "" -#: ../../en/rasters.rst:549 +#: ../../en/rasters.rst:702 msgid "A commonly used function that outputs geomvals is `ST_DumpAsPolygons `_, which returns a set of contiguous pixels with the same value as a polygon. Again this by default will only check band 1 and exclude no data values unless you override. This example selects only polygons from band 2. You can also apply filters to the values. For most use cases, :command:`ST_DumpAsPolygons` is a better option than :command:`ST_PixelAsPolygons` as it will return far fewer rows." msgstr "" -#: ../../en/rasters.rst:554 +#: ../../en/rasters.rst:707 msgid "This will output 6 rows, and return polygons corresponding to the letters in \"Raster\"." msgstr "" -#: ../../en/rasters.rst:565 +#: ../../en/rasters.rst:718 msgid "Note that it doesn't return a single geometry, because it finds continguous set of pixels with the same value that form a polygon. Even though all these values are the same, they are not continguous." msgstr "" -#: ../../en/rasters.rst:571 +#: ../../en/rasters.rst:724 msgid "A common approach to produce more complex geometries is to group by the values and union." msgstr "" -#: ../../en/rasters.rst:581 +#: ../../en/rasters.rst:734 msgid "This will give you 2 rows back corresponding to the words \"Raster\" and \"Hello\"." msgstr "" -#: ../../en/rasters.rst:585 +#: ../../en/rasters.rst:737 +msgid "Statistics" +msgstr "" + +#: ../../en/rasters.rst:738 +msgid "The most important thing to understand about rasters is that they are statistical tools for storing data in arrays, that you may happen to be able to make look pretty on a screen." +msgstr "" + +#: ../../en/rasters.rst:741 +msgid "You can find a menu of these statistical functions in `Raster Band Statistics `_." +msgstr "" + +#: ../../en/rasters.rst:745 +msgid "ST_SummaryStatsAgg and ST_SummaryStats" +msgstr "" + +#: ../../en/rasters.rst:747 +msgid "Want all stats for a set or rasters, reach for the function `ST_SummaryStatsAgg `_." +msgstr "" + +#: ../../en/rasters.rst:749 +msgid "This query takes about 10 seconds and gives you a summary of the whole table:" +msgstr "" + +#: ../../en/rasters.rst:756 +msgid "Outputs:" +msgstr "" + +#: ../../en/rasters.rst:765 +msgid "Which tells we have a lot of pixels and our max elevation is 411 ft." +msgstr "" + +#: ../../en/rasters.rst:767 +msgid "If you have built overviews, and just need a rough estimate of your mins, maxs, and means use one of your overviews. This next query returns roughly the same values for mins, maxs, and means as the prior but in about 1 second instead of 10." +msgstr "" + +#: ../../en/rasters.rst:776 +msgid "Now armed with this bit of information, we can ask more questions." +msgstr "" + +#: ../../en/rasters.rst:779 +msgid "ST_Histogram" +msgstr "" + +#: ../../en/rasters.rst:781 +msgid "Generally you won't want stats for your whole table, but instead just stats for a particular area, in that case, you'll want to also employ our old friends :command:`ST_Intersects` and :command:`ST_Clip`. If you are also in need of a raster statistics function that doesn't have an aggregate version, you'll want to carry :command:`ST_Union` along for the ride." +msgstr "" + +#: ../../en/rasters.rst:786 +msgid "For this next example we'll use a different stats function `ST_Histogram `_ which has no aggregate equivalent, and for this particular variant, is a set returning function. We are using the same area of interest as some prior examples, but we also need to employ geometry :command:`ST_Transform` to transform our NY state plane meters geometry to our NYC State Plane feet rasters. It is almost always more performant to transform the geometry instead of raster and definitely if your geometry is just a single one." +msgstr "" + +#: ../../en/rasters.rst:803 +msgid "the above query completes in under 60ms and outputs:" +msgstr "" + +#: ../../en/rasters.rst:817 +msgid "Creating Derivative Rasters" +msgstr "" + +#: ../../en/rasters.rst:818 +msgid "PostGIS raster comes packaged with a number of functions for editing rasters. These functions are both used for editing as well as creating derivative raster data sets. You will find these listed in `Raster Editors `_ and `Raster Management `_." +msgstr "" + +#: ../../en/rasters.rst:824 +msgid "Transforming rasters with ST_Transform" +msgstr "" + +#: ../../en/rasters.rst:825 +msgid "Most of our data is in NY State Plane meters (SRID: 26918), however our DEM raster dataset is in NY State Plane feet (SRID: 2263). For the least cumbersome workflow, we need our core datasets to be in the same spatial reference system." +msgstr "" + +#: ../../en/rasters.rst:829 +msgid "The `raster ST_Transform `_ is the function most suited for this job." +msgstr "" + +#: ../../en/rasters.rst:831 +msgid "In order to create a new nyc dem dataset in NY State Plane meters, we'll do the following:" +msgstr "" + +#: ../../en/rasters.rst:841 +msgid "The above on my system took about 1.5 minutes. For a larger data set it would take much longer." +msgstr "" + +#: ../../en/rasters.rst:844 +msgid "The aforementioned examples used two variants of the :command:`ST_Transform` raster function. The first was to get a reference raster that will be used to transform the other raster tiles to guarantee that all tiles have the same alignment. Note the second variant of :command:`ST_Transform` used doesn't even take an input SRID. This is because the SRID and all the pixel scale and block sizes are read from the reference raster. If you used `ST_Transform(rast, srid)` form, then all your rasters might come out with different alignment making it impossible to apply an operation such as :command:`ST_Union` on them." +msgstr "" + +#: ../../en/rasters.rst:851 +msgid "The only problem with the aforementioned :command:`ST_Transform` approach is that when you transform, the transformed often exists in other tiles. If you looked at the above output closely enough by outputting the convex hull of the rasters, in the next example" +msgstr "" + +#: ../../en/rasters.rst:855 +msgid "you'd see annoying overlaps around the borders." +msgstr "" + +#: ../../en/rasters.rst:864 +msgid "viewed in pgAdmin would look something like:" +msgstr "" + +#: ../../en/rasters.rst:870 +msgid "Using ST_MakeEmptyCoverage to create even tiled rasters" +msgstr "" + +#: ../../en/rasters.rst:871 +msgid "A better approach, albeit a bit slower, is to define your own coverage tile structure from scratch using `ST_MakeEmptyCoverage `_ and then find the intersecting tiles for each new tile, and ST_Union these and then use `ST_Transform(ref, ST_Union...)` to create each tile." +msgstr "" + +#: ../../en/rasters.rst:875 +msgid "For this we'll be using quite a few functions, we learned about earlier." +msgstr "" + +#: ../../en/rasters.rst:900 +msgid "Repeating the same exercise as earlier:" +msgstr "" + +#: ../../en/rasters.rst:909 +msgid "viewed in pgAdmin we no longer have overlaps:" +msgstr "" + +#: ../../en/rasters.rst:913 +msgid "On my system this took ~10 minutes and returned 3879 rows. After the creation of the table, we'll want to do the usual of adding a spatial index, primary key, and constraints as follows:" +msgstr "" + +#: ../../en/rasters.rst:928 +msgid "Which should take under 2 minutes for this dataset." +msgstr "" + +#: ../../en/rasters.rst:931 +msgid "Creating overview tables with ST_CreateOverview" +msgstr "" + +#: ../../en/rasters.rst:933 +msgid "Just as with our original dataset, it would be useful to have overview tables to speed up performance of some operations. `ST_CreateOverview `_ is a function fit for that purpose. You can use :command:`ST_CreateOverview` to create overviews also if you neglected to create one during the raster2pgsql load or you decided, you need more overviews." +msgstr "" + +#: ../../en/rasters.rst:939 +msgid "We'll create level 2 and 3 overviews as we had done with our original using this code." +msgstr "" + +#: ../../en/rasters.rst:946 +msgid "This process sadly takes a while, and a longer while the more rows you have so be patient. For this dataset it took about 3-5 minutes for the overview factor `2` and 1 minute for the overview factor `3`." +msgstr "" + +#: ../../en/rasters.rst:949 +msgid "The :command:`ST_CreateOverView` function also adds in the needed constraints so the columns appear with full detail in the `raster_columns` and `raster_overviews` catalogs. It does not add indexes to them though and also does not add an rid column. The rid column is probably not necessary unless you need a primary key to edit with. You would probably want an index which you can create with the following:" +msgstr "" + +#: ../../en/rasters.rst:964 +msgid "ST_CreateOverview has an optional argument for denoting the sampling method. If not specified it uses the default `NearestNeighbor` which is generally the fastest to compute but may not be ideal. Resampling methods is beyond the scope of this workshop." +msgstr "" + +#: ../../en/rasters.rst:970 +msgid "The intersection of rasters and geometries" +msgstr "" + +#: ../../en/rasters.rst:971 +msgid "There are a couple of functions commonly used to compute intersections of rasters and geometries. We've already seen :command:`ST_Clip` in action which returns the intersection of a raster and geometry as a raster, but there are others. For point data, the most commonly used is :command:`ST_Value` and then there is the :command:`ST_Intersection` which has several overloads some returning rasters and some returning a set of `geomval`." +msgstr "" + +#: ../../en/rasters.rst:979 +msgid "Pixel values at a geometric Point" +msgstr "" + +#: ../../en/rasters.rst:981 +msgid "If you need to return values from rasters based on intersection of several ad-hoc geometry points, you'll use `ST_Value `_ or it's nearest relative `ST_NearestValue `_." +msgstr "" + +#: ../../en/rasters.rst:995 +msgid "This example takes about 1 second to return 2444 rows. If you used :command:`ST_Intersects` instead of :command:`&&`, the process would take about 3 seconds. The reason `ST_Intersects` is slower is that it performs an additional recheck in some cases a pixel by pixel check. If you expect all your points to be represented with data in your raster set and your rasters represent a coverage (a continguous set non-overlapping raster tiles), then `&&` is generally a speedier option." +msgstr "" + +#: ../../en/rasters.rst:1000 +msgid "If your raster data is not densely populated or you have overlapping rasters (e.g. they represent different observations in time), or they are skewed (not axis aligned) then there is an advantage to having ST_Intersects weed out the false positives." +msgstr "" + +#: ../../en/rasters.rst:1006 +msgid "ST_Intersection raster style" +msgstr "" + +#: ../../en/rasters.rst:1007 +msgid "Just as you can compute the intersection of two geometries using :command:`ST_Intersection`, you can compute intersection of two rasters or a raster and a geometry using `raster ST_Intersection `_." +msgstr "" + +#: ../../en/rasters.rst:1011 +msgid "What you get out of this beast, are two different kinds of things:" +msgstr "" + +#: ../../en/rasters.rst:1013 +msgid "Intersect a geometry with a raster, and you get a set of `geomval` offspring. Perhaps one, but most often many." +msgstr "" + +#: ../../en/rasters.rst:1016 +msgid "Intersect 2 rasters and you get a single `raster` back." +msgstr "" + +#: ../../en/rasters.rst:1018 +msgid "The golden rule for both raster intersection and geometry intersection is that both parties involved must have the same spatial reference system. For raster/raster, they also have to have same alignment." +msgstr "" + +#: ../../en/rasters.rst:1022 +msgid "Here is an example which answers a question you may have been curious about. If we bucket our elevations into 5 buckets of elevation values, which elevation range results in the most gun fatalities? We know based on our earlier summary statistics that `0` is the lowest value and `411` is the highest value for elevation in our nyc dem dataset, so we use that as min and max value for our `width_bucket `_ call." +msgstr "" + +#: ../../en/rasters.rst:1044 +msgid "Is there an important correlation between gun homicides and elevation? Probably not." +msgstr "" + +#: ../../en/rasters.rst:1048 +msgid "Let's take a look at raster / raster intersection:" +msgstr "" + +#: ../../en/rasters.rst:1057 +msgid "What we get are two rows with NULLLs, and if you have your PostgreSQL set to show notices, you'll see:" +msgstr "" + +#: ../../en/rasters.rst:1059 +msgid "**NOTICE: The two rasters provided do not have the same alignment. Returning NULL**" +msgstr "" + +#: ../../en/rasters.rst:1061 +msgid "In order to fix this, we can align one to the other as it's coming out of the gate using `ST_Resample `_." +msgstr "" + +#: ../../en/rasters.rst:1071 +msgid "Let's also roll it up into a single stats record" +msgstr "" + +#: ../../en/rasters.rst:1083 +msgid "which outputs:" +msgstr "" + +#: ../../en/rasters.rst:1094 msgid "Map Algebra Functions" msgstr "" -#: ../../en/rasters.rst:586 -msgid "Map algebra is the idea that you can do math on your pixel values. The :command:`ST_Union` function covered earlier is a special fast case of map algebra. Then there are the `ST_MapAlgebra `_ family of functions which allow you to define your own crazy math, but at cost of performance." +#: ../../en/rasters.rst:1095 +msgid "Map algebra is the idea that you can do math on your pixel values. The :command:`ST_Union` and :command:`ST_Intersection` functions covered earlier are a special fast case of map algebra. Then there are the `ST_MapAlgebra `_ family of functions which allow you to define your own crazy math, but at cost of performance." msgstr "" -#: ../../en/rasters.rst:592 +#: ../../en/rasters.rst:1103 msgid "People have the habit of jumping to :command:`ST_MapAlgebra`, probably cause the name sounds so cool and sophisticated. Who wouldn't want to tell their friends, \"I'm using a function called ST_MapAlgebra.\" My advice, explore other functions before you jump for that shot-gun. Your life will be simpler and your performance will be 100 times better, and your code will be shorter." msgstr "" -#: ../../en/rasters.rst:598 +#: ../../en/rasters.rst:1109 +msgid "Before we showcase `ST_MapAlgebra`, we'll explore other functions that fit under the `Map Algebra` family of functions and generally have better performance than `ST_MapAlgebra`." +msgstr "" + +#: ../../en/rasters.rst:1113 +msgid "Reclassify your raster using ST_Reclass" +msgstr "" + +#: ../../en/rasters.rst:1115 msgid "An often overlooked map-algebraish function is the `ST_Reclass `_ function, who sits in the background waiting for someone to discover the power and speed it can offer." msgstr "" -#: ../../en/rasters.rst:602 +#: ../../en/rasters.rst:1119 msgid "What does **ST_Reclass** do? It as the name implies, reclassifies your pixel values based on minimalist range algebra." msgstr "" + +#: ../../en/rasters.rst:1121 +msgid "Lets revisit our NYC Dems. Perhaps we only care about classifying our elevations as 1) low, 2) medium, 3) high , and 4) really high. We don't need 411 values, we just need 4. With that said lets do some reclassifying." +msgstr "" + +#: ../../en/rasters.rst:1124 +msgid "The classification scheme is governed by the `reclass expression `_." +msgstr "" + +#: ../../en/rasters.rst:1140 +msgid "Which would output:" +msgstr "" + +#: ../../en/rasters.rst:1152 +msgid "If this were a classification scheme we preferred, we could create a new table using the ST_Reclass to recompute each tile." +msgstr "" + +#: ../../en/rasters.rst:1155 +msgid "Coloring your rasters with ST_ColorMap" +msgstr "" + +#: ../../en/rasters.rst:1156 +msgid "The `ST_ColorMap `_ function is another mapalgebraish function that reclassifies your pixel values. Except it is band creating. It converts a single band raster such as our Dems into a visually presentable 3 or 4 banded raster." +msgstr "" + +#: ../../en/rasters.rst:1160 +msgid "You could use one of the built-in colormaps as below if you don't want to fuss with creating one." +msgstr "" + +#: ../../en/rasters.rst:1171 +msgid "Which looks like:" +msgstr "" + +#: ../../en/rasters.rst:1175 +msgid "The bluer the color the lower the elevation and the redder the color the higher the elevation." +msgstr ""