vector_to_regular_points.json

{
    "id": "vector_to_regular_points",
    "summary": "Sample regular points from geometries",
    "description": "Generate a vector data cube of points by sampling regularly-spaced points from input geometries. Empty geometries are passed through without any points assigned. Feature properties are preserved.",
    "categories": [
        "cubes",
        "vector"
    ],
    "experimental": true,
    "parameters": [
        {
            "name": "data",
            "description": "Input geometries for sample extraction.",
            "schema": {
                "type": "object",
                "subtype": "datacube",
                "dimensions": [
                    {
                        "type": "geometry"
                    }
                ]
            }
        },
        {
            "name": "distance",
            "description": "Defines the minimum distance in meters that is required between two samples generated *inside* a single geometry. If the unit of the spatial reference system is not meters, a `UnitMismatch` error is thrown. Use ``vector_reproject()`` to convert the geometries to a suitable spatial reference system.\n\n- For **polygons**, the distance defines the cell sizes of a regular grid that starts at the upper-left bound of each polygon. The centroid of each cell is then a sample point. If the centroid is not enclosed in the polygon, no point is sampled. If no point can be sampled for the geometry at all, the first coordinate of the geometry is returned as point.\n- For **lines** (line strings), the sampling starts with a point at the first coordinate of the line and then walks along the line and samples a new point each time the distance to the previous point has been reached again.\n- For **points**, the point is returned as given.",
            "schema": {
                "type": "number",
                "minimumExclusive": 0
            }
        },
        {
            "name": "group",
            "description": "Specifies whether the sampled points should be grouped by input geometry (default) or be generated as independent points.\n\n* If the sampled points are grouped, the process generates a `MultiPoint` per geometry given which keeps the original identifier if present.\n* Otherwise, each sampled point is generated as a distinct `Point` geometry without identifier.",
            "optional": true,
            "default": true,
            "schema": {
                "type": "boolean"
            }
        }
    ],
    "returns": {
        "description": "Returns a vector data cube with the sampled points.",
        "schema": {
            "type": "object",
            "subtype": "datacube",
            "dimensions": [
                {
                    "type": "geometry",
                    "geometry_type": [
                        "Point",
                        "MultiPoint"
                    ]
                }
            ]
        }
    },
    "exceptions": {
        "UnitMismatch": {
            "message": "The unit of the spatial reference system is not meters, but the given distance is in meters."
        }
    }
}