# 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.

    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, 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.

    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 : 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.

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.