About Features Downloads Getting Started Documentation Events Support GitHub

Site Tools


Warning: This page has not been updated in over over a year and may be outdated or deprecated.
configuration:geographic_features

Geographic Features

properties
Page Ownerlmgonzales

Starting with VuFind 3.1, a new set of modules were introduced for displaying geographic data at the record level, as well as a geographic search interface.

  1. Provided the option for displaying multiple geographic features (points and/or rectangles) for a record.
  2. Provided a geographic search interface.
  3. Added configuration options for the geographic search and display interfaces.

To properly configure the Geographic Search & Display modules, you will need to ensure that your data is indexed properly, and then you will need to configure the module options in the associated .ini files.

For an overview of these features as they were originally developed for VuFind 3.1, you can download the presentation slides from the VuFind 2016 Summit for more information.

Changes from VuFind 4.x to 5.0

:!: Starting in VuFind 4.0, the OpenLayers functionality has been removed and replaced with Leaflet.

Other improvements include:

  • Improved search results clustering
  • Streamlining of configuration parameters, which are now all located in geofeatures.ini

Changes from VuFind 3.1 to 4.x

The VuFind 3.1.x version of these modules preserved and upgraded the VuFind 2.x GoogleMap functionality, so that it was compliant with the new Google API key requirements.

:!: Starting in VuFind 4.0, the GoogleMap functionality has been removed, some Solr schema details have been adjusted, and the Geographic Search & Display modules use OpenLayers exclusively. See pull request #995 to review the Google Map code that was removed.

Indexing Geographic Data

Each record can have one or more point and/or rectangle features with labels.

Coordinates

The coordinate data will go into field 034 of your MARC record, in subfields $d,$e,$f, and $g. You can format your coordinates as decimal degrees (DD) or degrees minutes seconds (DMS), and you can assign hemispheres by using either letters (N,S,E,W) or symbols (+,-). Note that the order for coordinates in the MARC 034 field, is: $d: West; $e: East; $f: North; $g: South

* Note, PR#1076 upgrades the code to allow for unsigned DD coordinates. With this patch, positive values do not need to be prefixed with the + sign.

If malformed coordinates are detected during indexing, an error message containing the record ID, coordinate values, and problems with the coordinate values will be displayed. Malformed coordinates will not be indexed.

Labels

Labels can be stored in the Solr database, and if you opt to do this, then put the labels in field 034 subfield $z. Alternatively, you have the option to use a look-up table to assign labels on the fly. If you use a look-up table, put the look-up table in your local/config/vufind/ directory.

Examples of MARC 034 field

Some examples of what the MARC record 034 field could look like are as follows:

Decimal degrees:

=034  0\$aa$d+46.4$e+40.4$f+31.5$g+28.50$zSite 447
=034  0\$aa$dE46.4$eE40.4$fN31.5$gN28.50$zSite 447

=034  0\$aa$dW10.1$eW10.1$fS5.7$gS5.7$zSite 440
=034  0\$aa$d-10.1$e-10.1$f-5.7$g-5.7$zSite 440

Degrees-minutes-seconds:

=034  0\$aa$dW1172630$eW1172630$fN661503$gN661503$zSite 393
=034  0\$aa$d+1172630$e+1172630$f+661503$g+661503$zSite 393

=034  0\$aa$dW0762630$eE0521915$fN051023$gS061503$zSite 980
=034  0\$aa$d-0762630$e+0521915$f+051023$g-061503$zSite 980

Solr fields and files

Starting in VuFind 4.0, the following Solr fields are used store geographic data:

  • long_lat: stores the coordinates as a bounding box field type and you can reference the Solr Spatial Guide (listed at the bottom of the slide) for more information on that.
  • long_lat_display: used for storing the coordinates that are used in the record's geographic display.
  • long_lat_label: used for storing the labels that are used in the record's geographic display.

:!: Note that VuFind 3.1 used the long_lat field differently and also relied on a location_geo field that was removed in 4.0. Details on the old 3.1 definitions are here:

  • location_geo: stores the coordinates as a bounding box field type and you can reference the Solr Spatial Guide (listed at the bottom of the slide) for more information on that.
  • long_lat: used for the GoogleMaps record geographic display.

The following files handle the indexing of geographic data:

  • schema.xml: Includes all the fields listed above, the _geo field type, and two dynamic fields: _geo and _geo_mv.
  • marc_local.properties: Includes all the fields listed above.
  • GeoTools.java: Contains the geographic indexing routines. (This code was found in VuFindIndexer.java prior to release 4.0).

Displaying Geographic Data

Starting with VuFind 5.0, geographic features are only displayed with Leaflet.

:!: In VuFind 4.x, geographic features are only displayed with OpenLayers.

:!: In VuFind 3.1, you have two options for displaying the geographic features of those records: OpenLayers or GoogleMaps.

Leaflet - VuFind 5.0 and Later

Leaflet provides a light-weight code base for displaying point and rectangle features, as well as their labels and coordinates. Features can be clicked on to show a popup window that will display the label and/or coordinates of that feature depending on how the [MapTab] section is configured in the geofeatures.ini file.

Notes:

  • The recordMap parameter in geofeatures.ini [MapTab] section has changed from a string to a boolean field in VuFind 5.0 so that it can be used to toggle the Map Tab display on and off.
  • The basemap is set in the [Basemap] section of geofeatures.ini

Configuration options for geographic feature display in the record's Map Tab from the geofeatures.ini file:

[Basemap]
basemap_url : the tileserver URL for the basemap
basemap_attribution: the attribution text for the basemap.

[MapTab]
recordMap = true ; OR false 
mapLabels = driver ; OR file:filename
displayCoords = true; OR false
graticule = true; OR false

Labels can be read from the long_lat_label field if they are stored in Solr, or assigned on the fly with a look-up table. If you use a look-up table, put it in your local/config/vufind/ directory, and in the geofeatures.ini file, set mapLabels = file:filename.

OpenLayers - VuFind 3.1 and 4.x only

OpenLayers allows you to display point and rectangle features, as well as their labels and coordinates. Features can be clicked on to show a popup window that will display the label and/or coordinates of that feature depending on how Geographic Display section is configured in the config.ini file. The pop-up window uses the built-in internationalization support so that as you switch languages, the title of the pop-up window (e.g., “At this location”) will be translated into the selected language.

Configuration options for OpenLayers display from config.ini file:

; Geographic Display
recordMap = openlayers
mapLabels = driver ; OR file:filename
displayCoords = true; OR false
graticule = true; OR false

Labels can be read from the long_lat_label field if they are stored in Solr, or assigned on the fly with a look-up table. If you use a look-up table, put it in your local/config/vufind/ directory, and in the config.ini file, set mapLabels = file:filename.

GoogleMaps - VuFind 3.1 only

:!: Support for the GoogleMaps display option is only available in VuFind 3.1; it is removed in later versions.

With this option you can only display point features and their labels. You must also supply the GoogleMaps API key in the Geographic Display section of the config.ini file.

Configuration options for GoogleMaps display from config.ini file:

; Geographic Display
recordMap = google
mapLabels = driver ; OR file:filename
displayCoords = false; **Not supported with GoogleMaps**
googleMapApiKey = API Key

Labels can be read from the long_lat_label field if they are stored in Solr, or assigned on the fly with a look-up table. If you use a look-up table, put it in your local/config/vufind/ directoryand in the config.ini file, set mapLabels = file:filename.

Note that display of coordinates is not supported with the GoogleMaps display option.

Geographic Searching

The geographic search interface can be accessed from the Search bar by clicking on the Geographic Search link. When the Geographic Search link is clicked, a default Solr bounding box query will run and will display the search box and the search results clustered on the map interface. You can zoom in to uncluster or zoom out to cluster the points.

In VuFind 5.0:

  • Features are clustered based on proximity. You can zoom in to uncluster features. Rectangle feature center points are denoted by marker icons with flat tops and point features are denoted with marker icons with rounded tops.
  • Click on an icon to see the title of the associated record.

In VuFind 4.x:

  • Any clusters with less than five records can be clicked on to show a pop-up with the list of titles in that cluster.
  • Additionally, you can click on a title in the pop-up to see the corresponding full record view.

You can also click on the Draw Search Box button, and then click and drag to create the search box query. (Note that the previous query box and results will persist as you draw your new search box. This is done on purpose to give you a reference point relative to the previous query.)

If you need help, just click on the Need Help? link next to the Draw Search Box button. The help text for geographic searching has been integrated into the VuFind help system so that the help is easier to maintain for translation purposes.

Starting in VuFind 4.0, the geographic search queries against the long_lat field and returns the data from the following fields: long_lat, title, id.

:!: In VuFind 3.1, the geographic search queries against the location_geo field and returns the data from the following fields: location_geo, title, id.

Configurable Options

To turn on the geographic search functionality, uncomment the MapSelection line in the Top Recommendations section of the searches.ini file:

default_top_recommend[] = MapSelection ; see [MapSelection] in geofeatures.ini

VuFind 5.0 and Later:

Set the default search box coordinates and the height of the map search interface in the [MapSelection] section of the geofeatures.ini file.

When setting your default search coordinates, try to focus the search on either an area with the most results or an area of high interest. Don’t make the search area too large or too small. You’ll probably have to play with the search interface to find the right setting.

[MapSelection]
; default_coordinates:  The default coordinates specified below are in decimal
;            degrees, and are ordered as WENS (west, east, north, south). Ranges of
;            valid values are:; -180 to 180 (longitude) and -85 to 85 (latitude).
;            Note, to search from and to the international date line, use
;            west = -179 and east = -180.
;
; height:    Height in pixels of the map selection interface.
default_coordinates = "-95, 30, 72, 15"
height = 320

VuFind 3.1 and 4.x:

Set the default search box coordinates and the height of the map search interface in the Map Selection section of the searches.ini file.

When setting your default search coordinates, try to focus the search on either an area with the most results or an area of high interest. Don’t make the search area too large or too small. You’ll probably have to play with the search interface to find the right setting.

[MapSelection]
; The default coordinates specified below are in decimal degrees, and are 
; ordered as WENS (west, east, north, south). Ranges of valid values are:
; -180 to 180 (longitude) and -85 to 85 (latitude). Note, to search from and to
; the international date line, use west = -179 and east = -180. 
default_coordinates = "-95, 30, 72, 15"
; height: Height in pixels of the map selection interface.
height = 320

Searching by Coordinate String

Another feature that is include in the Geographic Search code is the ability to search for records by entering a coordinate string. This will query against the long_lat_display field.

To configure this, you’ll need to turn on this feature in the searches.ini file in the Basic Searches and Advanced Searches sections, and if you want, the Autocomplete section as well.

[Basic_Searches]
;Coordinate = Coordinates

[Advanced_Searches]
;Coordinate = Coordinates

[Autocomplete_Types]
Coordinate = "None"

If you wish to change the configuration of the Coordinate field, update the corresponding section in the searchspecs.yaml file:

Coordinate:
  DismaxFields:
    - long_lat_display
DismaxHandler: edismax

Caveats for VuFind 3.1 and 4.x

The following functionality was upgraded in VuFind 5.0. In VuFind 5.0, all geographic features that intersect the search box are plotted. Center points for rectangle features are clustered and clusters, when hovered over show the range of center points contained within the cluster.

Clustering of Rectangle Features
Search results clustering requires that all clustered features be points. As such, the code calculates the center point for each rectangle feature. The code goes through several routines to check for rectangle features that intersect the search box, and to check if the center point of those rectangles land within the search box. For those rectangles that intersect the search box and have center points that fall outside of the search box, the code sets the rectangles' center points to the center of the search box.

Records with Multiple Geographic Features
For records that have multiple geographic features, only the first feature that falls within the search box is plotted in the search results.

Customizing the Geographic Search & Display Code

VuFind 5.0 and Later

The upgrades and code for the VuFind 5.0 implementation of the Geographic Features code can be found here: PR#1129

If you want to customize the Geographic Display code, you will need to modify these files:

  • RecordTab/map.phtml (also contains GoogleMap javascript code)
  • js/map_tab_leaflet.js
  • RecordTab/Factory.php
  • RecordTab/Map.php
  • RecordDriver/SolrDefault.php
  • GeoFeatures/MapTabConfig.php

If you want to customize the Geographic Search code, you will need to modify these files:

  • Recommend/MapSelection.phtml
  • search/searchbox.phtml (if enabled in searches.ini, Geographic Search option appears in search box.)
  • root/templates/HelpTranslations/en/geosearch.phtml (help text for geographic search module)
  • js/map_selection_leaflet.js
  • Recommend/MapSelection.php
  • GeoFeatures/MapSelectionConfig.php
  • View/Helper/Root/GeoCoords.php (returns geographic search query parameters).

The following files support both the Geographic Display and Geographic Search code:

Leaflet code:

  • js/vendor/leaflet/*
  • css/vendor/leaflet/*

configuration file:

  • geofeatures.ini

Helper methods:

  • GeoFeatures/AbstractConfig.php
  • GeoFeatures/BasemapConfig.php
  • GeoFeatures/AbstractConfig.php

RecordDriver/SolrDefault.php methods:

  • getGeoLocation
  • getDisplayCoordinates
  • getCoordinateLabels

CSS styling – add geoItem class for pop-ups to these files:

  • css/compiled.css
  • css/geofeatures.css
  • less/components/search.less

VuFind 3.1 and 4.x

The code for the geographic search & display features can be viewed on github here: PR#722

If you want to customize the Geographic Display code, you will need to modify these files:

  • RecordTab/map.phtml (also contains GoogleMap javascript code)
  • js/map_tab_ol.js (OpenLayers javascript code)
  • RecordTab/Factory.php
  • RecordTab/Map.php
  • RecordDriver/SolrDefault.php

If you want to customize the Geographic Search code, you will need to modify these files:

  • Recommend/MapSelection.phtml
  • search/searchbox.phtml (if enabled in searches.ini, Geographic Search option appears in search box.)
  • root/templates/HelpTranslations/en/geosearch.phtml (help text for geographic search module)
  • js/map_selection.js
  • Recommend/MapSelection.php
  • View/Helper/Root/GeoCoords.php (returns geographic search query parameters).

The following files support both the Geographic Display and Geographic Search code:

OpenLayers 3.17.1 code:

  • js/vendor/ol/ol.js , ol-debug.js
  • css/vendor/ol/ol.css

RecordDriver/SolrDefault.php methods:

  • getLongLat :!: VuFind 3.1. only
  • getGeoLocation
  • getDisplayCoordinates
  • getCoordinateLabels

CSS styling – add geoItem class for pop-ups to these files:

  • css/compiled.css
  • less/components/search.less
configuration/geographic_features.txt · Last modified: 2022/09/16 11:00 by demiankatz