pycoast.cw_base module

Base class for contour writers.

class pycoast.cw_base.ContourWriterBase(db_root_path=None)

Bases: object

Base class for contourwriters. Do not instantiate.

Parameters:

db_root_pathstr

Path to root dir of GSHHS and WDBII shapefiles

add_cities(image, area_def, cities_list, font_file, font_size=12, symbol='circle', ptsize=6, outline='black', fill='white', db_root_path=None, **kwargs)

Add cities (symbol and UTF-8 names as description) to a PIL image object.

Parameters:

imageobject

PIL image object

area_defobject

Area Definition of the provided image

cities_listlist of city names [‘City1’, ‘City2’, City3, …, ‘CityN’]

a list of UTF-8 or ASCII strings. If either of these strings is found

in file db_root_path/CITIES/cities.red, longitude and latitude is read

and the city is added like a point with its UTF-8 name as description

e.g. cities_list = [‘Zurich’, ‘Oslo’] will add cities ‘Zürich’, ‘Oslo’.

Check the README_PyCoast.txt in archive cities2022.zip for more details.

font_filestr

Path to font file

font_sizeint

Size of font

symbolstring

type of symbol, one of the elelments from the list [‘circle’, ‘hexagon’, ‘pentagon’, ‘square’, ‘triangle’, ‘star8’, ‘star7’, ‘star6’, ‘star5’, ‘asterisk’]

ptsizeint

Size of the point.

outlinestr or (R, G, B), optional

Line color of the symbol

fillstr or (R, G, B), optional

Filling color of the symbol

Optional keyword arguments:

widthfloat

Line width of the symbol

outline_opacityint, optional {0; 255}

Opacity of the line of the symbol.

fill_opacityint, optional {0; 255}

Opacity of the filling of the symbol

box_outlinestr or (R, G, B), optional

Line color of the textbox borders.

box_linewidthfloat

Line width of the the borders of the textbox

box_fillstr or (R, G, B), optional

Filling color of the background of the textbox.

box_opacityint, optional {0; 255}

Opacity of the background filling of the textbox.

add_overlay_from_config(config_file, area_def, background=None)

Create and return a transparent image adding all the overlays contained in a configuration file.

Parameters:

config_filestr

Configuration file name

area_defobject

Area Definition of the creating image

add_overlay_from_dict(overlays, area_def, cache_epoch=None, background=None)

Create and return a transparent image adding all the overlays contained in the overlays dict.

Optionally caches overlay results for faster rendering of images with the same provided AreaDefinition and parameters. Cached results are identified by hashing the AreaDefinition and the overlays dictionary.

Note that if background is provided and caching is not used, the result will be the final result of applying the overlays onto the background. This is due to an optimization step avoiding creating a separate overlay image in memory when it isn’t needed.

Warning

Font objects are ignored in parameter hashing as they can’t be easily hashed. Therefore, font changes will not trigger a new rendering for the cache.

Parameters:

overlaysdict

overlays configuration

area_defobject

Area Definition of the creating image

cache_epoch: seconds since epoch

The latest time allowed for cache the cache file. If the cache file is older than this (mtime), the cache should be regenerated. Defaults to 0 meaning always reuse the cached file if it exists. Requires “cache” to be configured in the provided dictionary (see below).

background: pillow image instance

The image on which to write the overlays on. If it’s None (default), a new image is created, otherwise the provide background is used and changed in place.

The keys in overlays that will be taken into account are: cache, coasts, rivers, borders, shapefiles, grid, cities, points

For all of them except cache, the items are the same as the corresponding functions in pycoast, so refer to the docstrings of these functions (add_coastlines, add_rivers, add_borders, add_shapefile_shapes, add_grid, add_cities, add_points). For cache, two parameters are configurable:

• file: specify the directory and the prefix

  of the file to save the caches decoration to (for example /var/run/black_coasts_red_borders)

• regenerate: True or False (default) to force the overwriting

  of an already cached file.

add_points(image, area_def, points_list, font_file, font_size=12, symbol='circle', ptsize=6, outline='black', fill='white', coord_ref='lonlat', **kwargs)

Add a symbol and/or text at the point(s) of interest to a PIL image object.

Parameters:

imageobject

PIL image object

area_defobject

Area Definition of the provided image

points_listlist [((x, y), desc)]

a list of points defined with (x, y) in float and a desc in string

[((x1, y1), desc1), ((x2, y2), desc2)]

See coord_ref (below) for the meaning of x, y.

x : float

longitude or pixel x of a point

y : float

latitude or pixel y of a point

desc : str

description of a point

font_filestr

Path to font file

font_sizeint

Size of font

symbolstring

type of symbol, one of the elelments from the list [‘circle’, ‘hexagon’, ‘pentagon’, ‘square’, ‘triangle’, ‘star8’, ‘star7’, ‘star6’, ‘star5, ‘asterisk’]

ptsizeint

Size of the point (should be zero if symbol:None).

outlinestr or (R, G, B), optional

Line color of the symbol

fillstr or (R, G, B), optional

Filling color of the symbol

Optional keyword arguments:

coord_refstring

The interpretation of x,y in points_list: ‘lonlat’ (the default: x is degrees E, y is degrees N), or ‘image’ (x is pixels right, y is pixels down). If image coordinates are negative they are interpreted relative to the end of the dimension like standard Python indexing.

widthfloat

Line width of the symbol

outline_opacityint, optional {0; 255}

Opacity of the line of the symbol.

fill_opacityint, optional {0; 255}

Opacity of the filling of the symbol

box_outlinestr or (R, G, B), optional

Line color of the textbox borders.

box_linewidthfloat

Line width of the the borders of the textbox

box_fillstr or (R, G, B), optional

Filling color of the background of the textbox.

box_opacityint, optional {0; 255}

Opacity of the background filling of the textbox.

add_shapes(image, area_def, shapes, feature_type=None, x_offset=0, y_offset=0, **kwargs)

Draw shape objects to PIL image.

Parameters:

imageImage

PIL Image to draw shapes on

area_def(proj_str, area_extent) or AreaDefinition

Geolocation information for the provided image

shapes: iterable

Series of shape objects from pyshp. Can also be a series of 2-element tuples where the first element is the shape object and the second is a dictionary of additional drawing parameters for this shape.

feature_type: str

‘polygon’ or ‘line’ or None for what to draw shapes as. Default is to draw the shape with the type in the shapefile.

kwargs:

Extra drawing keyword arguments for all shapes

draw_hexagon(draw, x, y, ptsize, **kwargs)

draw_pentagon(draw, x, y, ptsize, **kwargs)

draw_star(draw, symbol, x, y, ptsize, **kwargs)

draw_triangle(draw, x, y, ptsize, **kwargs)

property is_agg: bool

Get if we are using the ‘agg’ backend.

class pycoast.cw_base.GeoNamesCitiesParser(cities_filename: str)

Bases: object

Helper for parsing citiesN.txt files from GeoNames.org.

iter_cities_names_lon_lat(cities_list: list[str]) → Generator[tuple[str, float, float], None, None]

pycoast.cw_base.get_resolution_from_area(area_def)

Get the best resolution for an area definition.

pycoast.cw_base.hash_dict(dict_to_hash: dict) → str

Hash dict object by serializing with json.