gnome.utilities.map_canvas

Module to hold classes and suporting code for the map canvas for GNOME:

The drawing code for rendering to images in scripting mode, and also for pushing some rendering to the server.

Also used for making raster maps.

This should have the basic drawing stuff. Ideally nothing in here is GNOME-specific.

Module Contents

Classes

MapCanvas

A class to draw maps, etc.

GridLines

class to hold logic for determining where the gridlines should be

Viewport

Viewport
class gnome.utilities.map_canvas.MapCanvas(image_size=(800, 600), projection=None, viewport=None, preset_colors='BW', background_color='transparent', colordepth=8, **kwargs)

Bases: object

A class to draw maps, etc.

This class provides the ability to set a projection, and then change the viewport of the rendered map

All the drawing methods will project and scale and shift the points so the rendered image is projected and shows only what is in the viewport.

In addition, it keeps two image buffers: background and foreground. These can be rendered individually, and saved out either alone or composited.

This version uses a paletted (8 bit) image – may be updated for RGB images at some point.

create a new map image from scratch – specifying the size

Parameters:

image_size – (width, height) tuple of the image size in pixels

Optional parameters

Parameters:

  • projection=None – gnome.utilities.projections object to use. if None, it defaults to FlatEarthProjection()

  • viewport – viewport of map – what gets drawn and on what scale. Default is full globe: (((-180, -90), (180, 90)))

  • preset_colors='BW' –

    color set to preset. Options are:

    ’BW’ - transparent, black, and white:

    transparent background

    ’web’ - the basic named colors for the web:

    transparent background

    ’transparent’ - transparent background,

    no other colors set

    None - no pre-allocated colors
    – the first one you allocate will

    be the background color

  • 'transparent' (background_color =) – color for the background – must be a color that exists

  • colordepth=8 – only 8 bit color supported for now maybe someday, 32 bit will be an option

property viewport

returns the current value of viewport of map: the bounding box of the image

property image_size

makes it read-only

or we can add a setter to re-size the images if we need that

viewport_to_dict()

convert numpy arrays to list of tuples todo: this happens in multiple places so maybe worthwhile to define custom serialize/deserialize – but do this for now

set_viewport(BB=None, center=None, width=None, height=None)

Function to allow the user to set properties of the viewport in meters, or by bounding box

Parameters:

  • center (tuple of floats (lon, lat)) – The point around which the viewport is centered

  • width (float) – Width of the viewport in meters

  • height (float) – height of the viewport in meters

  • BB (a list of tuples containing of the lower left and top right coordinates: ((min_x, min_y),(max_x, max_y))) – Bounding box of the viewport (overrides all previous parameters)

zoom(multiplier)
shift_viewport(delta)
rescale()

Rescales the projection to the viewport bounding box. Should be called whenever the viewport changes

add_colors(color_list)

Add a list of colors to the pallette

Parameters:

color_list – list of colors. Each element of the list is a 2-tuple: (‘color_name’, (r,g,b))

add_color_ramp(color_scheme, min_val, max_val)

generate depth colors to the gd images :param color_scheme: color scheme to render images type: ‘magma’, ‘inferno’, ‘plasma’, ‘viridis’, ‘cividis’, ‘twilight’, ‘twilight_shifted’, ‘turbo’ :param min_val: value to map to the first color in the scheme :param max_val: value to map to the last color in the scheme

get_color_names()

returns all the names colors

create_images(preset_colors)
back_asarray()

return the background image as a numpy array

fore_asarray()

return the foreground image as a numpy array

clear_background()
clear_foreground()
copy_back_to_fore()

copy the background to the foreground

note: this will write over anything on the foreground image

draw_points(points, diameter=1, color='black', shape='round', background=False)

Draws a set of individual points all in the same color

Parameters:

  • points – a Nx2 numpy array, or something that can be turned into one

  • diameter=1 – diameter of the points in pixels.

  • color (string) – a named color.

  • shape (string) – what shape to draw, options are “round”, “x”.

  • background=False – whether to draw to the background image.

draw_polygon(points, line_color=None, fill_color=None, line_width=1, background=False)

Draw a polygon

Parameters:

  • points (Nx2 array of integers (or something that can be turned into one)) – sequence of points

  • line_color=None (color name (string) or index (int)) – the color of the outline

  • fill_color=None – the color of the filled polygon

  • line_width=1 – width of line

  • background=False – whether to draw to the background image.

draw_polyline(points, line_color, line_width=1, background=False)

Draw a polyline

Parameters:

  • points (Nx2 array of integers (or something that can be turned into one)) – sequence of points

  • line_color (color name or index) – the color of the outline

  • line_width=1 – width of line

  • background=False – whether to draw to the background image.

draw_text(text_list, size='small', color='black', align='lt', background=None, draw_to_back=False)

Draw ascii text to the image

Parameters:

  • text_list (['string', (lon, lat)]) – sequence of strings to be printed, and the locations they are to be located

  • size (one of the following strings: {'tiny', 'small', 'medium', 'large', 'giant'}) – size of the text to be printed

  • color (a valid color string in the py_gd Image color palettes) – color of the text to be printed

  • align (one of the following strings: {'lt', 'ct', 'rt', 'r', 'rb', 'cb', 'lb', 'l'}) – sets the principal point of the text bounding box.

draw_background()
draw_land()
draw_graticule(background=True)

draw a graticule (grid lines) on the map

only supports decimal degrees for now…

draw_grid()
draw_tags(draw_to_back=True)
save_background(filename, file_type='png')
save_foreground(filename, file_type='png')

save the foreground image to the specified filename

Parameters:

  • filename (string) – full path of file to be saved to

  • file_type (one of the following: {'png', 'gif', 'jpeg', 'bmp'}) – type of file to save

save(filename, file_type='png')

save the map image to the specified filename

This copies the foreground image on top of the background image and saves the whole thing.

Parameters:

  • filename (string) – full path of file to be saved to

  • file_type (one of the following: {'png', 'gif', 'jpeg', 'bmp'}) – type of file to save

class gnome.utilities.map_canvas.GridLines(viewport=None, projection=None, max_lines=10, DegMinSec=False)

Bases: object

class to hold logic for determining where the gridlines should be for the graticule

Creates a GridLines instance that does the logic for and describes the current graticule

Parameters:

  • viewport (tuple of lon/lat) – bounding box of the viewport in question.

  • max_lines (tuple of integers, (max, min)) – How many lines to be displayed on the longest dimension of the viewport. Graticule will scale up or down only when the number of lines in the viewport falls outside the range.

  • DegMinSec – Whether to scale by Degrees/Minute/Seconds, or decimal lon/lat

:type bool

DEGREE
MINUTE
SECOND
DMS_STEPS = ()
DMS_COUNT
DEGREE
TENTH
HUNDREDTH
THOUSANDTH
DEG_STEPS = ()
DEG_COUNT
get_step_size(reference_size)

Chooses the interval size for the graticule, based on where the reference size fits into the STEPS table.

Parameters:

reference_size – the approximate size you want in decimal degrees

get_lines()

Computes, builds, and returns a list of lines that when drawn, creates the graticule. The list consists of self.lon_lines vertical lines, followed by self.lat_lines horizontal lines.

refresh_scale()

Recomputes the interval and number of lines in each dimension. This should be called whenever the viewport changes.

set_max_lines(max_lines=None)

Alters the number of lines drawn.

Parameters:

max_lines (int) – the maximum number of lines drawn. (Note: this is NOT the number of lines on the screen at any given time. That is determined by the computed interval and the size/location of the viewport)

set_DMS(DMS=False)
Parameters:

DMS (Bool) – Boolean value that specifies if Degrees/Minutes/Seconds tags are enabled.

get_tags()

Returns a list of tags for each line (in the same order the lines are returned) and the position where the tag should be printed.

Line labels are anchored at the intersection between the line and the edge of the viewport. This may cause the longitude labels to disappear if the aspect ratio of the image and viewport are identical.

class gnome.utilities.map_canvas.Viewport(BB=None, center=None, width=None, height=None)

Bases: object

Viewport

class that defines and manages attribues for a viewport onto a flat 2D map. All points and measurements are in lon/lat

Init the viewport.

Can initialize with center/width/height, and/or with bounding box. NOTE: Bounding box takes precedence over any previous parameters

Parameters:

  • center (a tuple containing an lon/lat coordinate) – The point around which the viewport is centered

  • width – Width of the viewport (lon)

  • height – height of the viewport (lat)

  • BB (a list of lon/lat tuples containing the lower left and top right coordinates) – Bounding box of the viewport (overrides previous parameters)

property BB
property center
property width
property height
scale(multiplier=1.0)
recompute_dim()
recompute_BB()
aspect_ratio()