# pycoast package

## Submodules

## pycoast.cw_agg module

ContourWriter based on the aggdraw library.

class pycoast.cw_agg.ContourWriterAGG(db_root_path=None)

  Bases: `pycoast.cw_base.ContourWriterBase`

  Adds countours from GSHHS and WDBII to images using the AGG engine for high quality images.

  Parameters
    db_root_pathstr

      Path to root dir of GSHHS and WDBII shapefiles

  add_borders(image, area_def, resolution='c', level=1, outline='white', width=1, outline_opacity=255, x_offset=0, y_offset=0)

    Add borders to a PIL image object.

    Parameters
      imageobject

        PIL image object

      proj4_stringstr

        Projection of area as Proj.4 string

      area_extentlist

        Area extent as a list (LL_x, LL_y, UR_x, UR_y)

      resolutionstr, optional {‘c’, ‘l’, ‘i’, ‘h’, ‘f’}

        Dataset resolution to use

      levelint, optional {1, 2, 3}

        Detail level of dataset

      outlinestr or (R, G, B), optional

        Border color

      widthfloat, optional

        Width of coastline

      outline_opacityint, optional {0; 255}

        Opacity of coastline color

      x_offsetfloat, optional

        Pixel offset in x direction

      y_offsetfloat, optional

        Pixel offset in y direction

  add_borders_to_file(filename, area_def, resolution='c', level=1, outline='white', width=1, outline_opacity=255, x_offset=0, y_offset=0)

    Add borders to an image file. The resulting image is in ‘RGBA’ mode.

    Parameters
      imageobject

        Image file

      proj4_stringstr

        Projection of area as Proj.4 string

      area_extentlist

        Area extent as a list (LL_x, LL_y, UR_x, UR_y)

      resolutionstr, optional {‘c’, ‘l’, ‘i’, ‘h’, ‘f’}

        Dataset resolution to use

      levelint, optional {1, 2, 3}

        Detail level of dataset

      outlinestr or (R, G, B), optional

        Border color

      widthfloat, optional

        Width of coastline

      outline_opacityint, optional {0; 255}

        Opacity of coastline color

      x_offsetfloat, optional

        Pixel offset in x direction

      y_offsetfloat, optional

        Pixel offset in y direction

  add_coastlines(image, area_def, resolution='c', level=1, fill=None, fill_opacity=255, outline='white', width=1, outline_opacity=255, x_offset=0, y_offset=0)

    Add coastlines to a PIL image object.

    Parameters
      imageobject

        PIL image object

      proj4_stringstr

        Projection of area as Proj.4 string

      area_extentlist

        Area extent as a list (LL_x, LL_y, UR_x, UR_y)

      resolutionstr, optional {‘c’, ‘l’, ‘i’, ‘h’, ‘f’}

        Dataset resolution to use

      levelint, optional {1, 2, 3, 4}

        Detail level of dataset

      fillstr or (R, G, B), optional

        Land color

      fill_opacityint, optional {0; 255}

        Opacity of land color

      outlinestr or (R, G, B), optional

        Coastline color

      widthfloat, optional

        Width of coastline

      outline_opacityint, optional {0; 255}

        Opacity of coastline color

      x_offsetfloat, optional

        Pixel offset in x direction

      y_offsetfloat, optional

        Pixel offset in y direction

  add_coastlines_to_file(filename, area_def, resolution='c', level=1, fill=None, fill_opacity=255, outline='white', width=1, outline_opacity=255, x_offset=0, y_offset=0)

    Add coastlines to an image file. The resulting image is in ‘RGBA’ mode.

    Parameters
      filenamestr

        Image file

      proj4_stringstr

        Projection of area as Proj.4 string

      area_extentlist

        Area extent as a list (LL_x, LL_y, UR_x, UR_y)

      resolutionstr, optional {‘c’, ‘l’, ‘i’, ‘h’, ‘f’}

        Dataset resolution to use

      levelint, optional {1, 2, 3, 4}

        Detail level of dataset

      fillstr or (R, G, B), optional

        Land color

      fill_opacityint, optional {0; 255}

        Opacity of land color

      outlinestr or (R, G, B), optional

        Coastline color

      widthfloat, optional

        Width of coastline

      outline_opacityint, optional {0; 255}

        Opacity of coastline color

      x_offsetfloat, optional

        Pixel offset in x direction

      y_offsetfloat, optional

        Pixel offset in y direction

  add_grid(image, area_def, Dlonlat, dlonlat, font=None, write_text=True, fill=None, fill_opacity=255, outline='white', width=1, outline_opacity=255, minor_outline='white', minor_width=0.5, minor_outline_opacity=255, minor_is_tick=True, lon_placement='tb', lat_placement='lr')

    Add a lon-lat grid to a PIL image object.

    Parameters
      imageobject

        PIL image object

      proj4_stringstr

        Projection of area as Proj.4 string

      Dlonlat: (float, float)

        Major grid line separation

      dlonlat: (float, float)

        Minor grid line separation

      font: Aggdraw Font object, optional

        Font for major line markings

      write_textboolean, optional

        Deterine if line markings are enabled

      fill_opacityint, optional {0; 255}

        Opacity of text

      outlinestr or (R, G, B), optional

        Major line color

      widthfloat, optional

        Major line width

      outline_opacityint, optional {0; 255}

        Opacity of major lines

      minor_outlinestr or (R, G, B), optional

        Minor line/tick color

      minor_widthfloat, optional

        Minor line width

      minor_outline_opacityint, optional {0; 255}

        Opacity of minor lines/ticks

      minor_is_tickboolean, optional

        Use tick minor line style (True) or full minor line style (False)

  add_grid_to_file(filename, area_def, Dlonlat, dlonlat, font=None, write_text=True, fill=None, fill_opacity=255, outline='white', width=1, outline_opacity=255, minor_outline='white', minor_width=0.5, minor_outline_opacity=255, minor_is_tick=True, lon_placement='tb', lat_placement='lr')

    Add a lon-lat grid to an image. The resulting image is in ‘RGBA’ mode.

    Parameters
      imageobject

        PIL image object

      proj4_stringstr

        Projection of area as Proj.4 string

      Dlonlat: (float, float)

        Major grid line separation

      dlonlat: (float, float)

        Minor grid line separation

      font: Aggdraw Font object, optional

        Font for major line markings

      write_textboolean, optional

        Deterine if line markings are enabled

      fill_opacityint, optional {0; 255}

        Opacity of text

      outlinestr or (R, G, B), optional

        Major line color

      widthfloat, optional

        Major line width

      outline_opacityint, optional {0; 255}

        Opacity of major lines

      minor_outlinestr or (R, G, B), optional

        Minor line/tick color

      minor_widthfloat, optional

        Minor line width

      minor_outline_opacityint, optional {0; 255}

        Opacity of minor lines/ticks

      minor_is_tickboolean, optional

        Use tick minor line style (True) or full minor line style (False)

  add_line(image, area_def, lonlats, fill=None, fill_opacity=255, outline='white', width=1, outline_opacity=255, x_offset=0, y_offset=0)

    Add a user defined poly-line from a list of (lon,lat) coordinates.

    Parameters
      imageobject

        PIL image object

      area_deflist [proj4_string, area_extent]
        proj4_string : str
        Projection of area as Proj.4 string
        area_extent : list
        Area extent as a list (LL_x, LL_y, UR_x, UR_y)
      lonlatslist of lon lat pairs

        e.g. [(10,20),(20,30),…,(20,20)]

      outlinestr or (R, G, B), optional

        line color

      widthfloat, optional

        line width

      outline_opacityint, optional {0; 255}

        Opacity of lines

      x_offsetfloat, optional

        Pixel offset in x direction

      y_offsetfloat, optional

        Pixel offset in y direction

  add_polygon(image, area_def, lonlats, fill=None, fill_opacity=255, outline='white', width=1, outline_opacity=255, x_offset=0, y_offset=0)

    Add a user defined polygon from a list of (lon,lat) coordinates.

    Parameters
      imageobject

        PIL image object

      area_deflist [proj4_string, area_extent]
        proj4_string : str
        Projection of area as Proj.4 string
        area_extent : list
        Area extent as a list (LL_x, LL_y, UR_x, UR_y)
      lonlatslist of lon lat pairs

        e.g. [(10,20),(20,30),…,(20,20)]

      fillstr or (R, G, B), optional

        Polygon fill color

      fill_opacityint, optional {0; 255}

        Opacity of polygon fill

      outlinestr or (R, G, B), optional

        line color

      widthfloat, optional

        line width

      outline_opacityint, optional {0; 255}

        Opacity of lines

      x_offsetfloat, optional

        Pixel offset in x direction

      y_offsetfloat, optional

        Pixel offset in y direction

  add_rivers(image, area_def, resolution='c', level=1, outline='white', width=1, outline_opacity=255, x_offset=0, y_offset=0)

    Add rivers to a PIL image object.

    Parameters
      imageobject

        PIL image object

      proj4_stringstr

        Projection of area as Proj.4 string

      area_extentlist

        Area extent as a list (LL_x, LL_y, UR_x, UR_y)

      resolutionstr, optional {‘c’, ‘l’, ‘i’, ‘h’, ‘f’}

        Dataset resolution to use

      levelint, optional {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11}

        Detail level of dataset

      outlinestr or (R, G, B), optional

        River color

      widthfloat, optional

        Width of coastline

      outline_opacityint, optional {0; 255}

        Opacity of coastline color

      x_offsetfloat, optional

        Pixel offset in x direction

      y_offsetfloat, optional

        Pixel offset in y direction

  add_rivers_to_file(filename, area_def, resolution='c', level=1, outline='white', width=1, outline_opacity=255, x_offset=0, y_offset=0)

    Add rivers to an image file. The resulting image is in ‘RGBA’ mode.

    Parameters
      imageobject

        Image file

      proj4_stringstr

        Projection of area as Proj.4 string

      area_extentlist

        Area extent as a list (LL_x, LL_y, UR_x, UR_y)

      resolutionstr, optional {‘c’, ‘l’, ‘i’, ‘h’, ‘f’}

        Dataset resolution to use

      levelint, optional {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11}

        Detail level of dataset

      outlinestr or (R, G, B), optional

        River color

      widthfloat, optional

        Width of coastline

      outline_opacityint, optional {0; 255}

        Opacity of coastline color

      x_offsetfloat, optional

        Pixel offset in x direction

      y_offsetfloat, optional

        Pixel offset in y direction

  add_shapefile_shape(image, area_def, filename, shape_id, feature_type=None, fill=None, fill_opacity=255, outline='white', width=1, outline_opacity=255, x_offset=0, y_offset=0)

    Add a single shape file shape from an ESRI shapefile.

    Note: To add all shapes in file use the ‘add_shape_file_shapes’ routine

    Note: Currently only supports lon-lat formatted coordinates.

    Parameters
      imageobject

        PIL image object

      area_deflist [proj4_string, area_extent]
        proj4_string : str
        Projection of area as Proj.4 string
        area_extent : list
        Area extent as a list (LL_x, LL_y, UR_x, UR_y)
      filenamestr

        Path to ESRI shape file

      shape_idint

        integer id of shape in shape file {0; … }

      feature_type‘polygon’ or ‘line’,

        only to override the shape type defined in shapefile, optional

      fillstr or (R, G, B), optional

        Polygon fill color

      fill_opacityint, optional {0; 255}

        Opacity of polygon fill

      outlinestr or (R, G, B), optional

        line color

      widthfloat, optional

        line width

      outline_opacityint, optional {0; 255}

        Opacity of lines

      x_offsetfloat, optional

        Pixel offset in x direction

      y_offsetfloat, optional

        Pixel offset in y direction

  add_shapefile_shapes(image, area_def, filename, feature_type=None, fill=None, fill_opacity=255, outline='white', width=1, outline_opacity=255, x_offset=0, y_offset=0)

    Add shape file shapes from an ESRI shapefile.

    Note: Currently only supports lon-lat formatted coordinates.

    Parameters
      imageobject

        PIL image object

      area_deflist [proj4_string, area_extent]
        proj4_string : str
        Projection of area as Proj.4 string
        area_extent : list
        Area extent as a list (LL_x, LL_y, UR_x, UR_y)
      filenamestr

        Path to ESRI shape file

      feature_type‘polygon’ or ‘line’,

        only to override the shape type defined in shapefile, optional

      fillstr or (R, G, B), optional

        Polygon fill color

      fill_opacityint, optional {0; 255}

        Opacity of polygon fill

      outlinestr or (R, G, B), optional

        line color

      widthfloat, optional

        line width

      outline_opacityint, optional {0; 255}

        Opacity of lines

      x_offsetfloat, optional

        Pixel offset in x direction

      y_offsetfloat, optional

        Pixel offset in y direction

## 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, citylist, font_file, font_size, ptsize, outline, box_outline, box_opacity, db_root_path=None)

    Add cities (point and name) to a PIL image object.

  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.

    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, cities, points, grid

      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_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', **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 [((lon, lat), desc)]
        a list of points defined with (lon, lat) in float and a desc in string
        [((lon1, lat1), desc1), ((lon2, lat2), desc2)]
        lon : float
        longitude of a point
        lat : float
        latitude 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 elelment from the list [‘circle’, ‘square’, ‘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_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

class pycoast.cw_base.Proj(projparams: Optional[Any] = None, preserve_units: bool = True, **kwargs)

  Bases: `pyproj.proj.Proj`

  Wrapper around pyproj to add in ‘is_latlong’.

  is_latlong()

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_pil module

PIL-based ContourWriter.

class pycoast.cw_pil.ContourWriterPIL(db_root_path=None)

  Bases: `pycoast.cw_base.ContourWriterBase`

  Adds countours from GSHHS and WDBII to images.

  Parameters
    db_root_pathstr

      Path to root dir of GSHHS and WDBII shapefiles

  add_borders(image, area_def, resolution='c', level=1, outline='white', x_offset=0, y_offset=0)

    Add borders to a PIL image object.

    Parameters
      imageobject

        PIL image object

      proj4_stringstr

        Projection of area as Proj.4 string

      area_extentlist

        Area extent as a list (LL_x, LL_y, UR_x, UR_y)

      resolutionstr, optional {‘c’, ‘l’, ‘i’, ‘h’, ‘f’}

        Dataset resolution to use

      levelint, optional {1, 2, 3}

        Detail level of dataset

      outlinestr or (R, G, B), optional

        Border color

      x_offsetfloat, optional

        Pixel offset in x direction

      y_offsetfloat, optional

        Pixel offset in y direction

  add_borders_to_file(filename, area_def, resolution='c', level=1, outline='white', x_offset=0, y_offset=0)

    Add borders to an image file.

    Parameters
      imageobject

        Image file

      proj4_stringstr

        Projection of area as Proj.4 string

      area_extentlist

        Area extent as a list (LL_x, LL_y, UR_x, UR_y)

      resolutionstr, optional {‘c’, ‘l’, ‘i’, ‘h’, ‘f’}

        Dataset resolution to use

      levelint, optional {1, 2, 3}

        Detail level of dataset

      outlinestr or (R, G, B), optional

        Border color

      x_offsetfloat, optional

        Pixel offset in x direction

      y_offsetfloat, optional

        Pixel offset in y direction

  add_coastlines(image, area_def, resolution='c', level=1, fill=None, outline='white', x_offset=0, y_offset=0)

    Add coastlines to a PIL image object.

    Parameters
      imageobject

        PIL image object

      proj4_stringstr

        Projection of area as Proj.4 string

      area_extentlist

        Area extent as a list (LL_x, LL_y, UR_x, UR_y)

      resolutionstr, optional {‘c’, ‘l’, ‘i’, ‘h’, ‘f’}

        Dataset resolution to use

      levelint, optional {1, 2, 3, 4}

        Detail level of dataset

      fillstr or (R, G, B), optional

        Land color

      outlinestr or (R, G, B), optional

        Coastline color

      x_offsetfloat, optional

        Pixel offset in x direction

      y_offsetfloat, optional

        Pixel offset in y direction

  add_coastlines_to_file(filename, area_def, resolution='c', level=1, fill=None, outline='white', x_offset=0, y_offset=0)

    Add coastlines to an image file.

    Parameters
      filenamestr

        Image file

      proj4_stringstr

        Projection of area as Proj.4 string

      area_extentlist

        Area extent as a list (LL_x, LL_y, UR_x, UR_y)

      resolutionstr, optional {‘c’, ‘l’, ‘i’, ‘h’, ‘f’}

        Dataset resolution to use

      levelint, optional {1, 2, 3, 4}

        Detail level of dataset

      fillstr or (R, G, B)

        Land color

      outlinestr or (R, G, B), optional

        Coastline color

      x_offsetfloat, optional

        Pixel offset in x direction

      y_offsetfloat, optional

        Pixel offset in y direction

  add_grid(image, area_def, Dlonlat, dlonlat, font=None, write_text=True, fill=None, outline='white', minor_outline='white', minor_is_tick=True, lon_placement='tb', lat_placement='lr')

    Add a lon-lat grid to a PIL image object.

    Parameters
      imageobject

        PIL image object

      proj4_stringstr

        Projection of area as Proj.4 string

      Dlonlat: (float, float)

        Major grid line separation

      dlonlat: (float, float)

        Minor grid line separation

      font: PIL ImageFont object, optional

        Font for major line markings

      write_textboolean, optional

        Deterine if line markings are enabled

      fillstr or (R, G, B), optional

        Text color

      outlinestr or (R, G, B), optional

        Major line color

      minor_outlinestr or (R, G, B), optional

        Minor line/tick color

      minor_is_tickboolean, optional

        Use tick minor line style (True) or full minor line style (False)

  add_grid_to_file(filename, area_def, Dlonlat, dlonlat, font=None, write_text=True, fill=None, outline='white', minor_outline='white', minor_is_tick=True, lon_placement='tb', lat_placement='lr')

    Add a lon-lat grid to an image file.

    Parameters
      imageobject

        PIL image object

      proj4_stringstr

        Projection of area as Proj.4 string

      Dlonlat: (float, float)

        Major grid line separation

      dlonlat: (float, float)

        Minor grid line separation

      font: PIL ImageFont object, optional

        Font for major line markings

      write_textboolean, optional

        Deterine if line markings are enabled

      fillstr or (R, G, B), optional

        Text color

      outlinestr or (R, G, B), optional

        Major line color

      minor_outlinestr or (R, G, B), optional

        Minor line/tick color

      minor_is_tickboolean, optional

        Use tick minor line style (True) or full minor line style (False)

  add_line(image, area_def, lonlats, fill=None, outline='white', x_offset=0, y_offset=0)

    Add a user defined poly-line from a list of (lon,lat) coordinates.

    Parameters
      imageobject

        PIL image object

      area_deflist [proj4_string, area_extent]
        proj4_string : str
        Projection of area as Proj.4 string
        area_extent : list
        Area extent as a list (LL_x, LL_y, UR_x, UR_y)
      lonlatslist of lon lat pairs

        e.g. [(10,20),(20,30),…,(20,20)]

      outlinestr or (R, G, B), optional

        line color

      widthfloat, optional

        line width

      x_offsetfloat, optional

        Pixel offset in x direction

      y_offsetfloat, optional

        Pixel offset in y direction

  add_polygon(image, area_def, lonlats, fill=None, outline='white', x_offset=0, y_offset=0)

    Add a user defined polygon from a list of (lon,lat) coordinates.

    Parameters
      imageobject

        PIL image object

      area_deflist [proj4_string, area_extent]
        proj4_string : str
        Projection of area as Proj.4 string
        area_extent : list
        Area extent as a list (LL_x, LL_y, UR_x, UR_y)
      lonlatslist of lon lat pairs

        e.g. [(10,20),(20,30),…,(20,20)]

      fillstr or (R, G, B), optional

        Polygon fill color

      outlinestr or (R, G, B), optional

        line color

      x_offsetfloat, optional

        Pixel offset in x direction

      y_offsetfloat, optional

        Pixel offset in y direction

  add_rivers(image, area_def, resolution='c', level=1, outline='white', x_offset=0, y_offset=0)

    Add rivers to a PIL image object.

    Parameters
      imageobject

        PIL image object

      proj4_stringstr

        Projection of area as Proj.4 string

      area_extentlist

        Area extent as a list (LL_x, LL_y, UR_x, UR_y)

      resolutionstr, optional {‘c’, ‘l’, ‘i’, ‘h’, ‘f’}

        Dataset resolution to use

      levelint, optional {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11}

        Detail level of dataset

      outlinestr or (R, G, B), optional

        River color

      x_offsetfloat, optional

        Pixel offset in x direction

      y_offsetfloat, optional

        Pixel offset in y direction

  add_rivers_to_file(filename, area_def, resolution='c', level=1, outline='white', x_offset=0, y_offset=0)

    Add rivers to an image file.

    Parameters
      imageobject

        Image file

      proj4_stringstr

        Projection of area as Proj.4 string

      area_extentlist

        Area extent as a list (LL_x, LL_y, UR_x, UR_y)

      resolutionstr, optional {‘c’, ‘l’, ‘i’, ‘h’, ‘f’}

        Dataset resolution to use

      levelint, optional {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11}

        Detail level of dataset

      outlinestr or (R, G, B), optional

        River color

      x_offsetfloat, optional

        Pixel offset in x direction

      y_offsetfloat, optional

        Pixel offset in y direction

  add_shapefile_shape(image, area_def, filename, shape_id, feature_type=None, fill=None, outline='white', x_offset=0, y_offset=0)

    Add a single shape file shape from an ESRI shapefile.

    Note: To add all shapes in file use the ‘add_shape_file_shapes’ routine. Note: Currently only supports lon-lat formatted coordinates.

    Parameters
      imageobject

        PIL image object

      area_deflist [proj4_string, area_extent]
        proj4_string : str
        Projection of area as Proj.4 string
        area_extent : list
        Area extent as a list (LL_x, LL_y, UR_x, UR_y)
      filenamestr

        Path to ESRI shape file

      shape_idint

        integer id of shape in shape file {0; … }

      feature_type‘polygon’ or ‘line’,

        only to override the shape type defined in shapefile, optional

      fillstr or (R, G, B), optional

        Polygon fill color

      outlinestr or (R, G, B), optional

        line color

      x_offsetfloat, optional

        Pixel offset in x direction

      y_offsetfloat, optional

        Pixel offset in y direction

  add_shapefile_shapes(image, area_def, filename, feature_type=None, fill=None, outline='white', x_offset=0, y_offset=0)

    Add shape file shapes from an ESRI shapefile.

    Note: Currently only supports lon-lat formatted coordinates.

    Parameters
      imageobject

        PIL image object

      area_deflist [proj4_string, area_extent]
        proj4_string : str
        Projection of area as Proj.4 string
        area_extent : list
        Area extent as a list (LL_x, LL_y, UR_x, UR_y)
      filenamestr

        Path to ESRI shape file

      feature_type‘polygon’ or ‘line’,

        only to override the shape type defined in shapefile, optional

      fillstr or (R, G, B), optional

        Polygon fill color

      fill_opacityint, optional {0; 255}

        Opacity of polygon fill

      outlinestr or (R, G, B), optional

        line color

      outline_opacityint, optional {0; 255}

        Opacity of lines

      x_offsetfloat, optional

        Pixel offset in x direction

      y_offsetfloat, optional

        Pixel offset in y direction

## pycoast.version module

Git implementation of _version.py.

exception pycoast.version.NotThisMethod

  Bases: `Exception`

  Exception raised if a method is not valid for the current scenario.

class pycoast.version.VersioneerConfig

  Bases: `object`

  Container for Versioneer configuration parameters.

pycoast.version.get_config()

  Create, populate and return the VersioneerConfig() object.

pycoast.version.get_keywords()

  Get the keywords needed to look up the version information.

pycoast.version.get_versions()

  Get version information or return default if unable to do so.

pycoast.version.git_get_keywords(versionfile_abs)

  Extract version information from the given file.

pycoast.version.git_pieces_from_vcs(tag_prefix, root, verbose, run_command=<function run_command>)

  Get version from ‘git describe’ in the root of the source tree.

  This only gets called if the git-archive ‘subst’ keywords were not expanded, and _version.py hasn’t already been rewritten with a short version string, meaning we’re inside a checked out source tree.

pycoast.version.git_versions_from_keywords(keywords, tag_prefix, verbose)

  Get version information from git keywords.

pycoast.version.plus_or_dot(pieces)

  Return a + if we don’t already have one, else return a .

pycoast.version.register_vcs_handler(vcs, method)

  Decorator to mark a method as the handler for a particular VCS.

pycoast.version.render(pieces, style)

  Render the given version pieces into the requested style.

pycoast.version.render_git_describe(pieces)

  TAG[-DISTANCE-gHEX][-dirty].

  Like ‘git describe –tags –dirty –always’.

  Exceptions: 1: no tags. HEX[-dirty] (note: no ‘g’ prefix)

pycoast.version.render_git_describe_long(pieces)

  TAG-DISTANCE-gHEX[-dirty].

  Like ‘git describe –tags –dirty –always -long’. The distance/hash is unconditional.

  Exceptions: 1: no tags. HEX[-dirty] (note: no ‘g’ prefix)

pycoast.version.render_pep440(pieces)

  Build up version string, with post-release “local version identifier”.

  Our goal: TAG[+DISTANCE.gHEX[.dirty]] . Note that if you get a tagged build and then dirty it, you’ll get TAG+0.gHEX.dirty

  Exceptions: 1: no tags. git_describe was just HEX. 0+untagged.DISTANCE.gHEX[.dirty]

pycoast.version.render_pep440_old(pieces)

  TAG[.postDISTANCE[.dev0]] .

  The “.dev0” means dirty.

  Eexceptions: 1: no tags. 0.postDISTANCE[.dev0]

pycoast.version.render_pep440_post(pieces)

  TAG[.postDISTANCE[.dev0]+gHEX] .

  The “.dev0” means dirty. Note that .dev0 sorts backwards (a dirty tree will appear “older” than the corresponding clean one), but you shouldn’t be releasing software with -dirty anyways.

  Exceptions: 1: no tags. 0.postDISTANCE[.dev0]

pycoast.version.render_pep440_pre(pieces)

  TAG[.post.devDISTANCE] – No -dirty.

  Exceptions: 1: no tags. 0.post.devDISTANCE

pycoast.version.run_command(commands, args, cwd=None, verbose=False, hide_stderr=False, env=None)

  Call the given command(s).

pycoast.version.versions_from_parentdir(parentdir_prefix, root, verbose)

  Try to determine the version from the parent directory name.

  Source tarballs conventionally unpack into a directory that includes both the project name and a version string. We will also support searching up two directory levels for an appropriately named parent directory

## Module contents

Pycoast package for adding geographic-based decorations to images.

class pycoast.ContourWriter(*args, **kwargs)

  Bases: `pycoast.cw_pil.ContourWriterPIL`

  Writer wrapper for deprecation warning.

  Deprecated since version 1.2.0: Use `ContourWriterPIL` or `ContourWriterAGG` instead.