Class GIS

x.__init__(...) initializes x; see help(type(x)) for signature

Overrides: object.__init__

(inherited documentation)

Download a KML file:
    - unzip it if-required
    - follow NetworkLinks recursively if-required

Save the file to the /uploads folder

Designed to be called asynchronously using:
    current.s3task.async("download_kml", [record_id, filename])

@param record_id: id of the record in db.gis_layer_kml
@param filename: name to save the file as
@param session_id_name: name of the session
@param session_id: id of the session

@ToDo: Pass error messages to Result & have JavaScript listen for these

Fetch a KML file:

• unzip it if-required
• follow NetworkLinks recursively if-required

Returns a file object

Designed as a helper function for download_kml()

Geocode an Address
- used by S3LocationSelector
          settings.get_gis_geocode_imported_addresses

@param address: street address
@param postcode: postcode
@param Lx_ids: list of ancestor IDs
@param geocoder: which geocoder service to use

Reverse Geocode a Lat/Lon
- used by S3LocationSelector

Given a Start & End set of Coordinates, return a Bearing Formula from: http://www.movable-type.co.uk/scripts/latlong.html

            Calculate the Bounds of a list of Point Features, suitable for
            setting map bounds. If no features are supplied, the current map
            configuration bounds will be returned.
            e.g. When a map is displayed that focuses on a collection of points,
                 the map is zoomed to show just the region bounding the points.
            e.g. To use in GPX export for correct zooming
`
            Ensure a minimum size of bounding box, and that the points
            are inset from the border.

            @param features: A list of point features
            @param bbox_min_size: Minimum bounding box - gives a minimum width
                   and height in degrees for the region shown.
                   Without this, a map showing a single point would not show any
                   extent around that point.
            @param bbox_inset: Bounding box insets - adds a small amount of
                   distance outside the points.
                   Without this, the outermost points would be on the bounding
                   box, and might not be visible.
            @return: An appropriate map bounding box, as a dict:
                   dict(lon_min=lon_min, lat_min=lat_min,
                        lon_max=lon_max, lat_max=lat_max)

            @ToDo: Support Polygons (separate function?)
        

Get bounds from the specified (parent) location and its ancestors. This is used to validate lat, lon, and bounds for child locations.

Caution: This calls update_location_tree if the parent bounds are not set. During prepopulate, update_location_tree is disabled, so unless the parent contains its own bounds (i.e. they do not need to be propagated down from its ancestors), this will not provide a check on location nesting. Prepopulate data should be prepared to be correct. A set of candidate prepopulate data can be tested by importing after prepopulate is run.

Parameters:

• parent - A location_id to provide bounds suitable for validating child locations

Returns:

bounding box and parent location name, as a list: [lat_min, lon_min, lat_max, lon_max, parent_name]

Return a list of IDs of all GIS Features which are children of the requested feature, using Materialized path for retrieving the children

This has been chosen over Modified Preorder Tree Traversal for greater efficiency: http://eden.sahanafoundation.org/wiki/HaitiGISToDo#HierarchicalTrees

Returns:

Rows object containing IDs & Names Note: This does NOT include the parent location itself

Returns a list containing ancestors of the requested feature.

If the caller already has the location row, including path and parent fields, they can supply it via feature to avoid a db lookup.

If ids_only is false, each element in the list is a gluon.sql.Row containing the gis_location record of an ancestor of the specified location.

If ids_only is true, just returns a list of ids of the parents. This avoids a db lookup for the parents if the specified feature has a path.

List elements are in the opposite order as the location path and exclude the specified location itself, i.e. element 0 is the parent and the last element is the most distant ancestor.

Assists lazy update of a database without location paths by calling update_location_tree to get the path.

Note that during prepopulate, update_location_tree is disabled, in which case this will only return the immediate parent.

Adds ancestor of requested feature for each level to supplied dict.

If the caller already has the location row, including path and parent fields, they can supply it via feature to avoid a db lookup.

If a dict is not supplied in results, one is created. The results dict is returned in either case.

If ids=True and names=False (used by old S3LocationSelectorWidget): For each ancestor, an entry is added to results, like ancestor.level : ancestor.id

If ids=False and names=True (used by address_onvalidation): For each ancestor, an entry is added to results, like ancestor.level : ancestor.name

If ids=True and names=True (used by new S3LocationSelectorWidget): For each ancestor, an entry is added to results, like ancestor.level : {name : ancestor.name, id: ancestor.id}

Re-set table options that depend on location_hierarchy

Only update tables which are already defined

Reads the specified GIS config from the DB, caches it in response.

Passing in a false or non-existent id will cause the personal config, if any, to be used, else the site config (uuid SITE_DEFAULT), else their fallback values defined in this class.

If force_update_cache is true, the config will be read and cached in response even if the specified config is the same as what's already cached. Used when the config was just written.

The config itself will be available in response.s3.gis.config. Scalar fields from the gis_config record and its linked gis_projection record have the same names as the fields in their tables and can be accessed as response.s3.gis.<fieldname>.

Returns the id of the config it actually used, if any.

Returns the current GIS config structure.

Returns the location hierarchy and it's labels

@param: level - a specific level for which to lookup the label
@param: location - the location_id to lookup the location for
                   currently only the actual location is supported
                   @ToDo: Do a search of parents to allow this
                          lookup for any location

Returns the strict hierarchy value from the current config.

Returns the deepest level key (i.e. Ln) in the current hierarchy.
- used by gis_location_onvalidation()

Get the current hierarchy levels plus non-hierarchy levels.

Get current location hierarchy levels relevant for the user

Returns country code or L0 location id versus name for all countries.

The lookup is cached in the session

If key_type is "code", these are returned as an OrderedDict with country code as the key. If key_type is "id", then the location id is the key. In all cases, the value is the name.

Returns country name for given code or id from L0 locations.

The key can be either location id or country code, as specified by key_type.

Returns the parent country for a given record

Returns the default country for the active gis_config

Returns a gluon.sql.Rows of Features within a Polygon. The Polygon can be either a WKT string or the ID of a record in the gis_location table

Currently unused.

Given a gis_location record or a bounding box dict with keys lon_min, lon_max, lat_min, lat_max, construct a WKT polygon with points at the corners.

Compute a bounding box given a Radius (in km) of a LatLon Location

Note the order of the parameters.

@return a dict containing the bounds with keys min_lon, max_lon, min_lat, max_lat

See: http://janmatuschek.de/LatitudeLongitudeBoundingCoordinates

Returns Features within a Radius (in km) of a LatLon Location

Unused

Returns the Lat/Lon for a Feature

used by display_feature() in gis controller

Parameters:

• feature_id - the feature ID
• filter - Filter out results based on deployment_settings

Returns the locations for an XML export
- used by GIS.get_location_data() and S3PivotTable.geojson()

@ToDo: Support multiple locations for a single resource
       (e.g. a Project working in multiple Communities)

Returns the locations, markers and popup tooltips for an XML export e.g. Feature Layers or Search results (Feature Resources) e.g. Exports in KML, GeoRSS or GPX format

Called by S3REST: S3Resource.export_tree()

Returns a Marker dict
- called by xml.gis_encode() for non-geojson resources
- called by S3Map.widget() if no marker_fn supplied

Returns a Style dict
- called by S3Report.geojson()

Save a Screenshot of a saved map

Lookup Shapefile Layer polygons once per layer and not per-record

Called by S3REST: S3Resource.export_tree()

Lookup Theme Layer polygons once per layer and not per-record

Called by S3REST: S3Resource.export_tree()

Calculate the shortest distance (in km) over the earth's sphere between 2 points Formulae from: http://www.movable-type.co.uk/scripts/latlong.html (NB We could also use PostGIS functions, where possible, instead of this query)

Create a .poly file for OpenStreetMap exports http://wiki.openstreetmap.org/wiki/Osmosis/Polygon_Filter_File_Format

Export admin areas to /static/cache for use by interactive web-mapping services
- designed for use by the Vulnerability Mapping

@param countries: list of ISO2 country codes
@param levels: list of which Lx levels to export
@param format: Only GeoJSON supported for now (may add KML &/or OSM later)
@param simplify: tolerance for the simplification algorithm. False to disable simplification
@param precision: number of decimal points to include in the coordinates

Import Admin Boundaries into the Locations table

@param source - Source to get the data from.
                Currently only GADM is supported: http://gadm.org
@param countries - List of ISO2 countrycodes to download data for
                   defaults to all countries
@param levels - Which levels of the hierarchy to import.
                defaults to all 3 supported levels

Import L0 Admin Boundaries into the Locations table from GADMv1
- designed to be called from import_admin_areas()
- assumes that basic prepop has been done, so that no new records need to be created

@param ogr - The OGR Python module
@param countries - List of ISO2 countrycodes to download data for
                   defaults to all countries

Import L1 Admin Boundaries into the Locations table from GADMv1
- designed to be called from import_admin_areas()
- assumes a fresh database with just Countries imported

@param ogr - The OGR Python module
@param level - "L1" or "L2"
@param countries - List of ISO2 countrycodes to download data for
                   defaults to all countries

Import Admin Boundaries into the Locations table from GADMv2
- designed to be called from import_admin_areas()
- assumes that basic prepop has been done, so that no new L0 records need to be created

@param ogr - The OGR Python module
@param level - The OGR Python module
@param countries - List of ISO2 countrycodes to download data for
                   defaults to all countries

@ToDo: Complete this
    - not currently possible to get all data from the 1 file easily
    - no ISO2
    - needs updating for gis_location_tag model
    - only the lowest available levels accessible
    - use GADMv1 for L0, L1, L2 & GADMv2 for specific lower?

Import Locations from the Geonames database

Parameters:

• country - the 2-letter country code
• level - the ADM level to import

  Designed to be run from the CLI Levels should be imported sequentially. It is assumed that L0 exists in the DB already L1-L3 may have been imported from Shapefiles with Polygon info Geonames can then be used to populate the lower levels of hierarchy

Convert a LatLon to a WKT string

>>> s3gis.latlon_to_wkt(6, 80)
'POINT(80 6)'

Parses a location from wkt, returning wkt, lat, lon, bounding box and type. For points, wkt may be None if lat and lon are provided; wkt will be generated. For lines and polygons, the lat, lon returned represent the shape's centroid. Centroid and bounding box will be None if Shapely is not available.

Update GIS Locations' Materialized path, Lx locations, Lat/Lon & the_geom

@param feature: a feature dict to update the tree for
- if not provided then update the whole tree
@param all_locations: passed to recursive calls to indicate that this
is an update of the whole tree. Used to avoid repeated attempts to
update hierarchy locations with missing data (e.g. lacking some
ancestor level).
@param propagating: passed to recursive calls to indicate that this
is a propagation update. Used to avoid repeated attempts to
update hierarchy locations with missing data (e.g. lacking some
ancestor level).

returns the path of the feature

Called onaccept for locations (async, where-possible)

OnValidation callback:
If a WKT is defined: validate the format,
    calculate the LonLat of the Centroid, and set bounds
Else if a LonLat is defined: calculate the WKT for the Point.

Returns a query of all Locations inside the given bounding box

Returns Rows of Locations whose shape intersects the given bbox.

Returns Rows of locations which intersect the given shape.

Relies on Shapely for wkt parsing and intersection.

Returns a generator of locations whose shape intersects the given LatLon.

Relies on Shapely.

Returns all Locations whose geometry intersects the given feature.

Relies on Shapely.

Sets bounds for all locations without them.

If shapely is present, and a location has wkt, bounds of the geometry are used. Otherwise, the (lat, lon) are used as bounds.

Simplify a complex Polygon using the Douglas-Peucker algorithm
- NB This uses Python, better performance will be gained by doing
     this direct from the database if you are using PostGIS:
ST_Simplify() is available as
db(query).select(table.the_geom.st_simplify(tolerance).st_astext().with_alias('wkt')).first().wkt
db(query).select(table.the_geom.st_simplify(tolerance).st_asgeojson().with_alias('geojson')).first().geojson

@param wkt: the WKT string to be simplified (usually coming from a gis_location record)
@param tolerance: how aggressive a simplification to perform
@param preserve_topology: whether the simplified geometry should be maintained
@param output: whether to output as WKT or GeoJSON format
@param precision: the number of decimal places to include in the output

Returns the HTML to display a map

Normally called in the controller as: map = gis.show_map()
In the view, put: {{=XML(map)}}

@param id: ID to uniquely identify this map if there are several on a page
@param height: Height of viewport (if not provided then the default deployment setting is used)
@param width: Width of viewport (if not provided then the default deployment setting is used)
@param bbox: default Bounding Box of viewport (if not provided then the Lat/Lon/Zoom are used) (Dict):
    {"lon_min" : float,
     "lat_min" : float,
     "lon_max" : float,
     "lat_max" : float,
     }
@param lat: default Latitude of viewport (if not provided then the default setting from the Map Service Catalogue is used)
@param lon: default Longitude of viewport (if not provided then the default setting from the Map Service Catalogue is used)
@param zoom: default Zoom level of viewport (if not provided then the default setting from the Map Service Catalogue is used)
@param projection: EPSG code for the Projection to use (if not provided then the default setting from the Map Service Catalogue is used)
@param add_feature: Whether to include a DrawFeature control to allow adding a marker to the map
@param add_feature_active: Whether the DrawFeature control should be active by default
@param add_polygon: Whether to include a DrawFeature control to allow drawing a polygon over the map
@param add_polygon_active: Whether the DrawFeature control should be active by default
@param add_circle: Whether to include a DrawFeature control to allow drawing a circle over the map
@param add_circle_active: Whether the DrawFeature control should be active by default
@param features: Simple Features to overlay on Map (no control over appearance & not interactive)
    [wkt]
@param feature_queries: Feature Queries to overlay onto the map & their options (List of Dicts):
    [{"name"   : T("MyLabel"), # A string: the label for the layer
      "query"  : query,        # A gluon.sql.Rows of gis_locations, which can be from a simple query or a Join.
                               # Extra fields can be added for 'popup_url', 'popup_label' & either
                               # 'marker' (url/height/width) or 'shape' (with optional 'colour' & 'size')
      "active" : True,         # Is the feed displayed upon load or needs ticking to load afterwards?
      "marker" : None,         # Optional: A per-Layer marker query or marker_id for the icon used to display the feature
      "opacity" : 1,           # Optional
      "cluster_attribute",     # Optional
      "cluster_distance",      # Optional
      "cluster_threshold"      # Optional
      }]
@param feature_resources: REST URLs for (filtered) resources to overlay onto the map & their options (List of Dicts):
    [{"name"      : T("MyLabel"), # A string: the label for the layer
      "id"        : "search",     # A string: the id for the layer (for manipulation by JavaScript)
      "active"    : True,         # Is the feed displayed upon load or needs ticking to load afterwards?
      EITHER:
      "layer_id"  : 1,            # An integer: the layer_id to load (optional alternative to specifying URL/tablename/marker)
      "filter"    : "filter",     # A string: an optional URL filter which *replaces* any in the layer
      OR:
      "tablename" : "module_resource", # A string: the tablename (used to determine whether to locate via location_id or site_id)
      "url"       : "/eden/module/resource.geojson?filter", # A URL to load the resource

      "marker"    : None,         # Optional: A per-Layer marker dict for the icon used to display the feature (overrides layer_id if-set)
      "opacity"   : 1,            # Optional (overrides layer_id if-set)
      "cluster_attribute",        # Optional (overrides layer_id if-set)
      "cluster_distance",         # Optional (overrides layer_id if-set)
      "cluster_threshold",        # Optional (overrides layer_id if-set)
      "dir",                      # Optional (overrides layer_id if-set)
      "style",                    # Optional (overrides layer_id if-set)
      }]
@param wms_browser: WMS Server's GetCapabilities & options (dict)
    {"name": T("MyLabel"),     # Name for the Folder in LayerTree
     "url": string             # URL of GetCapabilities
     }
@param catalogue_layers: Show all the enabled Layers from the GIS Catalogue
                         Defaults to False: Just show the default Base layer
@param legend: True: Show the GeoExt Legend panel, False: No Panel, "float": New floating Legend Panel
@param toolbar: Show the Icon Toolbar of Controls
@param area: Show the Area tool on the Toolbar
@param color_picker: Show the Color Picker tool on the Toolbar (used for S3LocationSelector...pick up in postprocess)
                     If a style is provided then this is used as the default style
@param nav: Show the Navigation controls on the Toolbar
@param save: Show the Save tool on the Toolbar
@param search: Show the Geonames search box (requires a username to be configured)
@param mouse_position: Show the current coordinates in the bottom-right of the map. 3 Options: 'normal', 'mgrs', False (defaults to checking deployment_settings, which defaults to 'normal')
@param overview: Show the Overview Map (defaults to checking deployment_settings, which defaults to True)
@param permalink: Show the Permalink control (defaults to checking deployment_settings, which defaults to True)
@param scaleline: Show the ScaleLine control (defaults to checking deployment_settings, which defaults to True)
@param zoomcontrol: Show the Zoom control (defaults to checking deployment_settings, which defaults to True)
@param mgrs: Use the MGRS Control to select PDFs
    {"name": string,           # Name for the Control
     "url": string             # URL of PDF server
     }
    @ToDo: Also add MGRS Search support: http://gxp.opengeo.org/master/examples/mgrs.html
@param window: Have viewport pop out of page into a resizable window
@param window_hide: Have the window hidden by default, ready to appear (e.g. on clicking a button)
@param closable: In Window mode, whether the window is closable or not
@param collapsed: Start the Tools panel (West region) collapsed
@param callback: Code to run once the Map JavaScript has loaded
@param plugins: an iterable of objects which support the following methods:
                    .extend_gis_map(map)
                Client-side portion suppoprts the following methods:
                    .addToMapWindow(items)
                    .setup(map)

disable_update_location_tree

Value:

False