random-land-points 1.1.0

Sampling random points from non-convex polygons and land areas

Random Land Points

This is a little package that allows you to randomly sample points on land. This can be done either for all land masses, by continent, or by country.

Installation

pip install random-land-points

Usage

This package can be used to get random points on land in a provided polygon or in a specific country.

To sample you can use the random_points function. This function returns a random point on land in the provided polygon. All points are returned as a list of numpy arrays with the first element being the longitude and the second element being the latitude. That is [lon, lat].

import random_land_points as rlp

# Get a random point on land
point = rlp.random_points() # Point is [lon, lat]

# Get 10 random points on land
points = rlp.random_points(count=10)

You can also sample points by continent or by country. To do this, you can pass the continent or country name as an argument to the random_points function.

import random_land_points as rlp

# Get a random point on land in Europe
point = rlp.random_points('Europe')

# Get a random point on land in Italy
point = rlp.random_points('Italy')

The package utilizes the Natural Earth dataset to get the land polygons for each country. The data set comes in 3 resolutions: 10m high, 50m medium, and 110m low. The default resolution is medium, but you can specify the resolution by passing the resolution argument to the random_points and get_countries functions. The number of polygons and the available countries vary by resolution.

An example of this is shown below:

import random_land_points as rlp

# Get all high resolution countries
countries = rlp.get_countries(resolution='high')

# Get a random point on land in a high resolution country
point = rlp.random_points('Italy', resolution='high')

If you need to get the list of all supported countries, you can use the get_countries function.

import random_land_points as rlp

countries = rlp.get_countries()

To sample from a specific polygon, you can use the random_point_in_polygon function. This function takes a Shapely polygon as an argument and returns a random point on land in that polygon.

import random_land_points as rlp
from shapely.geometry import Polygon

# Create a polygon
polygon = Polygon([(0, 0), (1, 0), (1, 1), (0, 1)])

# Get a random point on land in the polygon
point = rlp.random_point_in_polygon(polygon)

You can check whether a given (x,y) coordinate is contained within a generating polygon by using the is_in function. This function returns a boolean value indicating whether the point is contained within the generating polygon.

import random_land_points as rlp

# Check if a point is in the generating polygon
rlp.is_in(0.0, 0.0) # False

# Check by country
rlp.is_in_country(0.0, 0.0, 'Italy') # False

# Check by continent
rlp.is_in_continent(0.0, 0.0, 'Europe') # False

Examples

There are examples found in the examples directory. These examples show how to use the package to get random points on land and visualize the results.

To run the examples install the package with [examples] option:

pip install random-land-points[examples]

Then run the examples with the following command:

python ./examples/random_points.py
python ./examples/random_by_continent.py
python ./examples/random_by_country.py

Development

To install the package for development, you can use the following command:

pip install -e ".[dev]"

To run the tests, you can use the following command:

pytest

License

This package is licensed under the MIT license. See the LICENSE file for more details.

Acknowledgements

Made with Natural Earth. Free vector and raster map data @ naturalearthdata.com.