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.

Classes¶

`MapCanvas`	A class to draw maps, etc.
`GridLines`	class to hold logic for determining where the gridlines should be
`Viewport`	Viewport

Module Contents¶

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

background_color = 'transparent'¶

projection¶

graticule¶

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

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

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

property image_size¶

makes it read-only

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

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’

Parameters:

min_val – value to map to the first color in the scheme
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.

Fixme: filename & file_type appear to not be used at all here.: Are we passing them in to satisfy some api specification?

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 = 21¶

TENTH¶

HUNDREDTH¶

THOUSANDTH¶

DEG_STEPS¶

DEG_COUNT = 19¶

viewport = None¶

projection = None¶

DMS = False¶

max_lines = 10¶

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)

scale(multiplier=1.0)¶

recompute_dim()¶

recompute_BB()¶

aspect_ratio()¶

property BB¶

property center¶

property width¶

property height¶