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 foundin file db_root_path/CITIES/cities.red, longitude and latitude is readand the city is added like a point with its UTF-8 name as descriptione.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.
See
add_overlay_from_dict()
for more information.- Parameters:
- config_filestr
Configuration file name
- area_defobject
Area Definition of the creating image
- Returns:
PIL.Image.Image
Resulting overlays as an Image object. If caching was used then the Image wraps an open file and should be closed by the caller. If caching was not used or the cached image was recreated then this is an in-memory Image object. Regardless, it can be closed by calling the
.close()
method of the 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 provided 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, pointsFor 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.
- Returns:
PIL.Image.Image
Resulting overlays as an Image object. If caching was used then the Image wraps an open file and should be closed by the caller. If caching was not used or the cached image was recreated then this is an in-memory Image object. Regardless, it can be closed by calling the
.close()
method of the Image.
- 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 : floatlongitude or pixel x of a pointy : floatlatitude or pixel y of a pointdesc : strdescription 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.
- 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.
- pycoast.cw_base.iter_cities_names_lon_lat(cities_filename: str | Path, cities_list: list[str]) Generator[tuple[str, float, float], None, None]
Iterate over citiesN.txt files from GeoNames.org.