gnome.maps.map¶

GNOME land-water map.

Maps for the GNOME Model – maps are responsible for determining where / when elements impact the shoreline

The module includes a base map that is all water – no land, As well as a few implementations of actual maps

Classes¶

`GnomeMap`	The very simplest map for GNOME -- all water
`ParamMap`	The very simplest map for GNOME -- all water
`RasterMap`	A land water map implemented as a raster
`MapFromBNA`	A raster land-water map, created from file with polygons in it.
`MapFromUGrid`	A raster land-water map, created from netcdf File of a UGrid

Functions¶

`ShiftLon360`(points)
`ShiftLon180`(points)
`map_from_rectangular_grid`(mask, lon, lat[, refine])	Suitable for a rectangular, but not fully regular, grid
`grid_from_nc`(filename)	generates a grid_mask and lat lon from a conforming netcdf file
`map_from_rectangular_grid_nc_file`(filename[, refine])	builds a raster map from a rectangular grid in a netcdf file
`refine_axis`(old_axis, refine)	refines the axis be interpolating points between each axis points
`map_from_regular_grid`(grid_mask, lon, lat[, refine, ...])	note: untested -- here to save it in case we need it in the future

Module Contents¶

class gnome.maps.map.GnomeMap(map_bounds=None, spillable_area=None, land_polys=None, **kwargs)¶

Bases: gnome.gnomeobject.GnomeId

The very simplest map for GNOME – all water with only a bounding box for the map bounds.

This also serves as a description of the interface and base class for more complex maps

The __init__ will be different for other implementations

Parameters:

map_bounds – The polygon bounding the map if any elements are outside the map bounds, they are removed from the simulation.
spillable_area (Either a PolygonSet object or a list of lists from which a polygon set can be created. Each element in the list is a list of points defining a polygon.) – The PolygonSet bounding the spillable_area.
land_polys (Either a PolygonSet object or a list of lists from which a polygon set can be created. Each element in the list is a list of points defining a polygon.) – The PolygonSet holding the land polygons

Note on ‘map_bounds’:: [(lon, lat), (lon, lat), (lon, lat), .. An NX2 array of points that describe a polygon if no map bounds is provided – the whole world is valid

refloat_halflife = None¶

property spillable_area¶: List of polygons defining the region in which it is legal to set spills

property land_polys¶: Sequence of polygons surrounding land – mostly used for rendering.

get_polygons()¶

property map_bounds¶

Bounds of the map – an NX2 array of float describing a polygon.

[(lon, lat), (lon, lat), …]

get_map_bounding_box()¶

return a bounding box of the map

needed because map_bounds can be a polygon

bounding box is a 2x2 tuple:

((left, bottom), (right, top))

on_map(coords)¶

Determine whether points are on the map or not

Parameters:: coords (NX3 numpy array of floats: (long, lat, depth) or something that can be turned into one.) – location for test.
Returns:: bool array: True if the location is on the map, False otherwise

Note:: coords are 3-d, but the concept of “on the map” is 2-d in this context, so depth is ignored.

on_land(coord)¶

Parameters:

coord (3-tuple of floats: (long, lat, depth)) – location for test.

Returns:

Always returns False– no land in this implementation

in_water(coords)¶

Determines if the points are in water (rather than on land)

Parameters:

coords (3-tuple of floats: (long, lat, depth) or an Nx3 array) – location for test.

Returns:

True if the point is in the water,
False if the point is on land (or off map?)

This implementation has no land, so always True in on the map.

allowable_spill_position(coord)¶

Parameters:

coord (3-tuple of floats: (long, lat, depth)) – location for test.

Returns:

True if the point is an allowable spill position
False if the point is not an allowable spill position

Note

it could be either off the map, or in a location that spills aren’t allowed

beach_elements(sc, model_time=None)¶

Determines which LEs were or weren’t beached or moved off_map. status_code is changed to oil_status.off_maps if off the map.

Called by the model in the main time loop, after all movers have acted.

Parameters:: sc (gnome.spill_container.SpillContainer) – current SpillContainer

This map class has no land, so only the map check and resurface_airborn elements is done: noting else changes.

subclasses that override this probably want to make sure that:

self.resurface_airborne_elements(sc) self._set_off_map_status(sc)

are called.

refloat_elements(spill_container, time_step, model_time=None)¶

This method performs the re-float logic – changing the element status flag, and moving the element to the last known water position

Parameters:: spill_container (gnome.spill_container.SpillContainer) – current SpillContainer

Note

This map class has no land, and so is a no-op.

resurface_airborne_elements(spill_container)¶

Takes any elements that are left above the water surface (z < 0.0) and puts them on the surface (z == 0.0)

Parameters:: spill_container (gnome.spill_container.SpillContainer) – current SpillContainer

Note

While this shouldn’t occur according to the physics we’re modeling, some movers may push elements up too high, or multiple movers may add vertical movement that adds up to over the surface. e.g rise velocity.

to_geojson()¶

class gnome.maps.map.ParamMap(center=(0.0, 0.0), distance=30000, bearing=90, units=None, **kwargs)¶

Bases: GnomeMap

The very simplest map for GNOME – all water with only a bounding box for the map bounds.

This also serves as a description of the interface and base class for more complex maps

Creates a parameratized map, essentially a straight shoreline set a certain distance and bearing from a location, usually a spill. It is up to the user to put the spill and the map center in the same location.

Required arguments:

Parameters:

center – tuple of coordinates describing the center point of the map
distance – The distance in meters the closest point on the shoreline is from the center
bearing – The bearing the closest point on the shoreline is from the center.

build(center, distance, bearing, units)¶

property distance¶

get_map_bounds()¶

get_land_polygon()¶

on_map(coord)¶

Parameters:: coord (3-tuple of floats: (long, lat, depth)) – location for test.
Returns:: bool array: True if the location is on the map, False otherwise

Note:: coord is 3-d, but the concept of “on the map” is 2-d in this context, so depth is ignored.

on_land(coord)¶

Parameters:

coord (3-tuple of floats: (long, lat, depth) or Nx3 numpy array) – location for test.

Returns:

Always returns False– no land in this implementation

in_water(coord)¶

Parameters:

coord (3-tuple of floats: (long, lat, depth)) – location for test.

Returns:

True if the point is in the water,
False if the point is on land (or off map?)

This implementation has no land, so always True in on the map.

allowable_spill_position(coord)¶

Parameters:

coord (3-tuple of floats: (long, lat, depth)) – location for test.

Returns:

True if the point is an allowable spill position
False if the point is not an allowable spill position

Note

it could be either off the map, or in a location that spills aren’t allowed

find_last_water_pos(starts, ends)¶

beach_elements(sc, model_time=None)¶

Determines which LEs were or weren’t beached or moved off_map. status_code is changed to oil_status.off_maps if off the map.

Called by the model in the main time loop, after all movers have acted.

Parameters:: sc (gnome.spill_container.SpillContainer) – current SpillContainer

This map class does not use a raster map for collision detection. Since the land is so simple the collisions are detected via intersection.

refloat_elements(spill_container, time_step, model_time=None)¶

This method performs the re-float logic – changing the element status flag, and moving the element to the last known water position

Parameters:: spill_container (gnome.spill_container.SpillContainer) – the current spill container

update_from_dict(data)¶

to_geojson()¶

class gnome.maps.map.RasterMap(raster=None, projection=None, refloat_halflife=1, **kwargs)¶

Bases: GnomeMap

A land water map implemented as a raster

This one uses a numpy array of uint8, so there are 8 bits to choose from…

It requires a constant refloat half-life in hours

This will usually be initialized in a sub-class (from a BNA, etc) NOTE: Nothing new added to _state attribute for serialization

create a new RasterMap

Parameters:

raster (a (W,H) numpy array of type uint8) – A numpy array that stores the land-water map 0 is water. 1 is land. In theory, other values could be used for other purposes. If the array is not C-contiguous, it will be copied to a C-contiguus array.
projection (gnome.map_canvas.Projection) – A Projection object – used to convert from lat-long to pixels in the array

Optional arguments (kwargs)

Parameters:

refloat_halflife (float. Units are hours) – The halflife for refloating off land – assumed to be the same for all land. 0.0 means all refloat every time step < 0.0 means never re-float.
map_bounds ((N,2) numpy array of floats) – The polygon bounding the map – could be larger or smaller than the land raster
spillable_area ((N,2) numpy array of floats) – The polygon bounding the spillable_area
id (string) – unique ID of the object. Using UUID as a string. This is only used when loading object from save file.

seconds_in_hour = 3600¶

land_flag = 1¶

projection = None¶

build_coarser_rasters()¶

Builds the list which contains the different resolution raster maps. Scale -> raster example for base map of 1024 x 1024: 0 -> 1/16th raster 64 base cells per cell 1 -> 1/32nd raster 32:1 2 -> 1/64th raster 16:1 3 -> 1/128th raster 8:1 4 -> 1/256th raster 4:1 5 -> 1/512th raster 2:1 6 -> 1/1024th raster (== base map 1:1)

The general idea is that the particle position (an int) can quickly be mapped into any scale and the path can begin from there. For example, if your path begins offshore and ends in a narrow inlet, your scale might begin on the 32:1 map. But as soon as the path crosses into the (32:1) raster cell containing the inlet (which will register as a land cell on that raster), the scale will decrease to 4:1, when the cell is completely water. In the end, if the scale decreases to 1:1 and there’s still a land hit, then land was hit.

property ratios¶

property raster¶

property refloat_halflife¶

property approximate_raster_interval¶

save_as_image(filename)¶

Save the land-water raster as a PNG save_as_image

Parameters:: filename – the name of the file to save to.

on_land(coord)¶

Parameters:

coord (3-tuple of floats -- (long, lat, depth)) – (long, lat, depth) location – depth is ignored here.

Returns:

1 if point on land
0 if not on land

Note

to_pixel() converts to array of points…

in_water(coord)¶

checks if it’s on the map, first.: (depth is ignored in this version)

Parameters:: coord – (lon, lat, depth) coordinate
Returns:: true if the point given by coord is in the water

beach_elements(sc, model_time=None)¶

Determines which elements were or weren’t beached.

Any that are beached have the beached flag set, and a “last known water position” (lkwp) is computed

This version uses a modified Bresenham algorithm to find out which pixels the LE may have crossed.

Parameters:: sc (gnome.spill_container.SpillContainer It must have the following data arrays: (‘prev_position’, ‘positions’, ‘last_water_pt’, ‘status_code’)) – the current spill container

refloat_elements(spill_container, time_step, model_time=None)¶

This method performs the re-float logic – changing the element status flag, and moving the element to the last known water position

Parameters:: spill_container (gnome.spill_container.SpillContainer) – the current spill container

allowable_spill_position(coord)¶

Returns true if the spill position is in the allowable spill area

Note

This may not be the same as in_water!

Parameters:: coord – (lon, lat, depth) coordinate

to_pixel_array(coords)¶

Projects an array of (lon, lat) tuples onto the raster, and modifies it in place to hold the corresponding projected values.

Parameters:: coords – a numpy array of (lon, lat, depth) points
Returns:: a numpy array of (x, y) pixel values

gnome.maps.map.ShiftLon360(points)¶

gnome.maps.map.ShiftLon180(points)¶

class gnome.maps.map.MapFromBNA(filename, raster_size=4096 * 4096, map_bounds=None, spillable_area=None, shift_lons=0, **kwargs)¶

Bases: RasterMap

A raster land-water map, created from file with polygons in it.

Currently only support BNA, but could be shapefile, or ???

Creates a RasterMap from a data file. It is expected that you will get the spillable area and map bounds from the data file – if they exist

Required arguments:

Parameters:

filename – full path to the data file
raster_size (integer) – the total number of pixels (bytes) to make the raster – the actual size will match the aspect ratio of the bounding box of the land
shiftLons (integer) – shift longitudes to be in -180 to 180 coords or 0 to 360. 180, or 360 are valid inputs

Optional arguments (kwargs):

Parameters:

refloat_halflife – the half-life (in hours) for the re-floating.
map_bounds – The polygon bounding the map – could be larger or smaller than the land raster
spillable_area – The polygon bounding the spillable_area
id (string) – unique ID of the object. Using UUID as a string. This is only used when loading object from save file.

filename¶

shift_lons = 0¶

build_raster(land_polys=None, BB=None)¶

Build the underlying raster used for the map

This should be called if the resolution or land polygons change

property raster_size¶: Maximum physical size of the raster in bytes

to_geojson()¶

Output the vector version of the shoreline polygons.

This is what gets drawn in the WebGNOME client, for example

This version directly writes the polygons already stored in the map object – keeping the door open to that data coming from something other than a bna file.

FIXME: Technically, geojson recommends ccw polygons – but putting that: check in was pretty slow, so it’s commented out.

FIXME: This really should export the map_bounds and spillable_area as well.

class gnome.maps.map.MapFromUGrid(filename, raster_size=1024 * 1024, **kwargs)¶

Bases: RasterMap

A raster land-water map, created from netcdf File of a UGrid

Creates a GnomeMap (specifically a RasterMap) from a netcdf data file with a triangular mesh grid in it. The spillable area and map bounds need to be supplied – there is currently no way to express that in a netcdf file.

Required arguments:

Parameters:

filename – full path to the data file
refloat_halflife – the half-life (in hours) for the re-floating.
raster_size (integer) – the total number of pixels (bytes) to make the raster – the actual size will match the aspect ratio of the bounding box of the land

Optional arguments (kwargs):

Parameters:

map_bounds – The polygon bounding the map – could be larger or smaller than the land raster
spillable_area – The polygon bounding the spillable_area
id (string) – unique ID of the object. Using UUID as a string. This is only used when loading object from save file.

filename¶

name¶: define as property in base class so all objects will have a name by default

gnome.maps.map.map_from_rectangular_grid(mask, lon, lat, refine=1, **kwargs)¶

Suitable for a rectangular, but not fully regular, grid

Such that it can be described by single longitude and latitude vectors

Parameters:

mask – the land-water mask as a numpy array
lon – longitude array
lon – latitude array
refine=1 – amount to refine grid – 4 will give 4 times the resolution
kwargs – Other keyword arguments are passed on to RasterMap

gnome.maps.map.grid_from_nc(filename)¶

generates a grid_mask and lat lon from a conforming netcdf file

NOTE: poorly tested, and will only work on a regular grid

gnome.maps.map.map_from_rectangular_grid_nc_file(filename, refine=1, **kwargs)¶

builds a raster map from a rectangular grid in a netcdf file

only tested with the HYCOM grid

Parameters:

filename (string) – the full path or opendap url for the netcdf file
refine (integer) – how much to refine the grid. 1 means keep it as it is, otherwise is will scale
kwargs – other key word arguemnts – passed on to RasterMap class constructor

gnome.maps.map.refine_axis(old_axis, refine)¶

refines the axis be interpolating points between each axis points

Parameters:

old_axis (1-d numpy array of floats) – the axis values
refine (integer) – amount to refine grid – 4 will give 4 times the resolution

gnome.maps.map.map_from_regular_grid(grid_mask, lon, lat, refine=4, refloat_halflife=1, map_bounds=None)¶

note: untested – here to save it in case we need it in the future

makes a raster map from a regular grid: i.e delta_lon and delta-lat are constant.