{"id":13734062,"url":"https://github.com/mapbox/postgis-vt-util","last_synced_at":"2025-05-08T10:30:56.316Z","repository":{"id":20558608,"uuid":"23838597","full_name":"mapbox/postgis-vt-util","owner":"mapbox","description":"postgres helper functions for making vector tiles","archived":false,"fork":false,"pushed_at":"2020-05-15T22:53:45.000Z","size":61,"stargazers_count":274,"open_issues_count":5,"forks_count":63,"subscribers_count":138,"default_branch":"master","last_synced_at":"2025-04-21T08:56:55.678Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PLpgSQL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mapbox.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-09-09T15:13:53.000Z","updated_at":"2024-12-10T12:58:11.000Z","dependencies_parsed_at":"2022-09-06T10:50:32.883Z","dependency_job_id":null,"html_url":"https://github.com/mapbox/postgis-vt-util","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapbox%2Fpostgis-vt-util","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapbox%2Fpostgis-vt-util/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapbox%2Fpostgis-vt-util/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapbox%2Fpostgis-vt-util/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mapbox","download_url":"https://codeload.github.com/mapbox/postgis-vt-util/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253045612,"owners_count":21845736,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T03:00:52.167Z","updated_at":"2025-05-08T10:30:56.059Z","avatar_url":"https://github.com/mapbox.png","language":"PLpgSQL","funding_links":[],"categories":["Database","PLpgSQL"],"sub_categories":[],"readme":"PostGIS Vector Tile Utils [![Build Status](https://travis-ci.org/mapbox/postgis-vt-util.svg?branch=master)](https://travis-ci.org/mapbox/postgis-vt-util)\n=========================\n\nA set of PostgreSQL functions that are useful when creating vector tile sources,\neither at the query stage in [Mapbox Studio][1] or in the earlier data\npreparation stages.\n\n[1]: http://mapbox.com/mapbox-studio\n\nInstallation\n------------\n\nEverything you need is in `postgis-vt-util.sql`. This project is also\navailable [as an NPM module][2] if that's useful to your workflow.\n\n[2]: https://www.npmjs.com/package/@mapbox/postgis-vt-util\n\nLoad the file into your database with `psql` or whatever your usual method is.\nEg:\n\n    psql -U \u003cusername\u003e -d \u003cdbname\u003e -f postgis-vt-util.sql\n\nFunction Reference\n------------------\n\n\u003c!-- DO NOT EDIT BELOW THIS LINE - AUTO-GENERATED FROM SQL COMMENTS --\u003e\n\n\n### Bounds ###\n\nReturns an array of the bounding coordinates of the input geometry -\n`{xmin, ymin, xmax, ymax}`. Useful for interfacing with software outside of\nPostGIS, among other things.\n\nIf an SRID is specified the output will be the bounds of the reprojected\ngeometry, not a reprojected bounding box.\n\n__Parameters:__\n\n- `geometry` g - Any geometry\n- `integer` srid (optional) - The desired output SRID of the bounds, if\n  different from the input.\n\n__Returns:__ `float[]` - an array of 4 floats, `{xmin, ymin, xmax, ymax}`\n\n\n### CleanInt ###\n\nReturns the input text as an integer if possible, otherwise null.\n\n__Parameters:__\n\n- `text` i - Text that you would like as an integer.\n\n__Returns:__ `integer`\n\n\n### CleanNumeric ###\n\nReturns the input text as an numeric if possible, otherwise null.\n\n__Parameters:__\n\n- `text` i - Text that you would like as an numeric.\n\n__Returns:__ `numeric`\n\n\n### LabelGrid ###\n\nReturns a \"hash\" of a geometry's position on a specified grid to use in a GROUP\nBY clause. Useful for limiting the density of points or calculating a localized\nimportance ranking.\n\nThis function is most useful on point geometries intended for label placement\n(eg points of interest) but will accept any geometry type. It is usually used\nas part of either a `DISTINCT ON` expression or a `rank()` window function.\n\n__Parameters:__\n\n- `geometry` g - A geometry.\n- `numeric` grid_size - The cell size of the desired grouping grid.\n\n__Returns:__ `text` - A text representation of the labelgrid cell\n\n__Example Mapbox Studio query:__\n\n```sql\n(   SELECT * FROM (\n        SELECT DISTINCT ON (LabelGrid(geom, 64*!pixel_width!)) * FROM (\n            SELECT id, name, class, population, geom FROM city_points\n            WHERE geom \u0026\u0026 !bbox!\n        ) AS raw\n        ORDER BY LabelGrid(geom, 64*!pixel_width!), population DESC, id\n    ) AS filtered\n    ORDER BY population DESC, id\n) AS final\n```\n\n\n### LargestPart ###\n\nReturns the largest single part of a multigeometry.\n\n- Given a multipolygon or a geometrycollection containing at least one polygon,\n  this function will return the single polygon with the largest area.\n- Given a multilinestring or a geometrycollection containing at least one\n  linestring and no polygons, this function will return the single linestring\n  with the longest length.\n- Given a single point, line, or polygon, the original geometry will be\n  returned.\n- Given any other geometry type the result of `ST_GeometryN(\u003cgeom\u003e, 1)` will be\n  returned. (See the documentation for that function.)\n\n__Parameters:__\n\n- `geometry` g - A geometry.\n\n__Returns:__ `geometry` - The largest single part of the input geometry.\n\n\n### LineLabel ###\n\nThis function tries to estimate whether a line geometry would be long enough to\nhave the given text placed along it at the specified scale.\n\nIt is useful in vector tile queries to filter short lines from zoom levels\nwhere they would be unlikely to have text places on them anyway.\n\n__Parameters:__\n\n- `numeric` zoom - The Web Mercator zoom level you are considering.\n- `text` label - The label text that you will be placing along the line.\n- `geometry(linestring)` g - A line geometry.\n\n__Returns:__ `boolean`\n\n\n### MakeArc ###\n\nCreates a CircularString arc based on 3 input points.\n\n__Parameters:__\n\n- `geometry(point)` p0 - The starting point of the arc.\n- `geometry(point)` p1 - A point along the path of the arc.\n- `geometry(point)` p2 - The end point of the arc.\n- `integer` srid (optional) - Sets the SRID of the output geometry. Useful\n  when input points have no SRID. If not specified the SRID of the first\n  input geometry will be assigned to the output.\n\n__Returns:__ `geometry(linestring)`\n\n__Examples:__\n\n\n```sql\nSELECT MakeArc(\n    ST_MakePoint(-100, 0),\n    ST_MakePoint(0, 100),\n    ST_MakePoint(100, 0),\n    3857\n);\n```\n\n\n### MercBuffer ###\n\nWraps ST_Buffer to adjust the buffer distance by latitude in order to\napproximate real-world measurements. Assumes input geometries are Web Mercator\nand input distances are real-world meters. Accuracy decreases for larger buffer\ndistances and at extreme latitudes.\n\n__Parameters:__\n\n- `geometry` g - A geometry to buffer.\n- `numeric` distance - The distance you would like to buffer, in real-world\n  meters.\n\n__Returns:__ `geometry`\n\n\n### MercDWithin ###\n\nWrapper for ST_DWithin that adjusts distance by latitude to approximate real-\nworld measurements. Assumes input geometries are Web Mercator and input\ndistances are real-world meters. Accuracy decreases for larger distances and at\nextreme latitudes.\n\n__Parameters:__\n\n- `geometry` g1 - The first geometry.\n- `geometry` g2 - The second geometry.\n- `numeric` distance - The maximum distance to check against\n\n__Returns:__ `boolean`\n\n\n### MercLength ###\n\nWrapper for ST_Length that adjusts distance by latitude to approximate real-\nworld measurements. Assumes input geometries are Web Mercator.  Accuracy\ndecreases for larger y-axis ranges of the input.\n\n__Parameters:__\n\n- `geometry` g - A (multi)linestring geometry.\n\n__Returns:__ `numeric`\n\n\n### OrientedEnvelope ###\n\nReturns an oriented minimum-bounding rectangle for a geometry.\n\n__Parameters:__\n\n- `geometry` g - A geometry.\n\n__Returns:__ `geometry(polygon)`\n\n\n### Sieve ###\n\nFilters small rings (both inner and outer) from a multipolygon based on area.\n\n__Parameters:__\n\n- `geometry` g - A multipolygon\n- `float` area_threshold - the minimum ring area to keep.\n\n__Returns:__ `geometry` - a polygon or multipolygon\n\n\n### SmartShrink ###\n\nBuffers a polygon progressively (on an exponential scale) until the\narea of the result hits a certain threshold ratio to the original area.\nThe result is also simplified with a tolerance matching the inset\ndistance.\n\n__Parameters:__\n\n- `geometry` g - A (multi)polygon.\n- `float` ratio - The threshold for how much smaller (by area) you want\n  the shrunk polygon to be compared to the original. Eg a value of 0.6\n  would result in a polygon that is at least 60% as large as the input.\n- `boolean` simplify - Defaults to false. Whether or not you would\n  like the shrunk geometry simplified.\n\n__Returns:__ `geometry`\n\n\n### TileBBox ###\n\nGiven a Web Mercator tile ID as (z, x, y), returns a bounding-box\ngeometry of the area covered by that tile.\n\n__Parameters:__\n\n- `integer` z - A tile zoom level.\n- `integer` x - A tile x-position.\n- `integer` y - A tile y-position.\n- `integer` srid - SRID of the desired target projection of the bounding\n  box. Defaults to 3857 (Web Mercator).\n\n__Returns:__ `geometry(polygon)`\n\n\n### ToPoint ###\n\nHelper to wrap ST_PointOnSurface, ST_MakeValid. This is needed because\nof a ST_PointOnSurface bug in geos \u003c 3.3.8 where POLYGON EMPTY can pass\nthrough as a polygon geometry.\nIf the input geometry is a polygon with less than 5 points the ST_Centroid\nof the polygon will be used instead of ST_PointOnSurface to speed up calculation.\n\n__Parameters:__\n\n- `geometry` g - A geometry.\n\n__Returns:__ `geometry(point)`\n\n__Example:__\n\n```sql\n-- Create an additional point geometry colums for labeling\nALTER TABLE city_park ADD COLUMN geom_label geometry(point);\nUPDATE city_park SET geom_label = ToPoint(geom);\n```\n\n\n### ZRES ###\n\nTakes a web mercator zoom level and returns the pixel resolution for that\nscale, assuming 256x256 pixel tiles. Non-integer zoom levels are accepted.\n\n__Parameters:__\n\n- `integer` or `float` z - A Web Mercator zoom level.\n\n__Returns:__ `float`\n\n__Examples:__\n\n```sql\n-- Delete all polygons smaller than 1px square at zoom level 10\nDELETE FROM water_polygons WHERE sqrt(ST_Area(geom)) \u003c ZRes(10);\n\n-- Simplify geometries to a resolution appropriate for zoom level 10\nUPDATE water_polygons SET geom = ST_Simplify(geom, ZRes(10));\n```\n\n\n### Z ###\n\nReturns a Web Mercator integer zoom level given a scale denominator.\n\nUseful with Mapnik's !scale_denominator! token in vector tile source\nqueries.\n\n__Parameters:__\n\n- `numeric` scale_denominator - The denominator of the scale, eg `250000`\n  for a 1:250,000 scale.\n\n__Returns:__ `integer`\n\n__Example Mapbox Studio query:__\n\n```sql\n( SELECT * FROM roads\n  WHERE Z(!scale_denominator!) \u003e= 12\n) AS data\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmapbox%2Fpostgis-vt-util","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmapbox%2Fpostgis-vt-util","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmapbox%2Fpostgis-vt-util/lists"}