Teth­er­ing to Post­GIS

In Teth­ered mode, Map­board GIS can turn over all spa­tial pro­cess­ing func­tion­al­ity to a cen­tral­ized Post­GIS data­base. Post­GIS is an ex­tremely pop­u­lar and wide­spread open-source spa­tial data­base sys­tem that can be used within most mod­ern GIS ap­pli­ca­tions.

Of­fload­ing spa­tial op­er­a­tions to a server-side data­base has sev­eral ad­van­tages:

• It en­ables work against much larger datasets than an iPad can han­dle lo­cally.
• It al­lows real-time in­ter­op­er­abil­ity with other GIS sys­tems (e.g. draw­ing in Map­board GIS can be paired with data clean­ing in QGIS)
• It al­lows col­lab­o­ra­tive map­ping, with mul­ti­ple iPads teth­ered to the same spa­tial data­base.

The core spa­tial server

Topo­log­i­cal func­tions are not re­quired for a ba­sic con­nec­tion to Post­GIS. In its sim­plest form, Teth­ered mode re­quires a con­nec­tion to a net­worked server run­ning Map­board’s server ex­ten­sions, or an­other server im­ple­ment­ing the same ex­ter­nal in­ter­face.

This server re­lies on a sim­ple schema of four spa­tial ta­bles within a Post­GIS data­base: linework, linework_type, polygon, and polygon_type. These are the same core ta­bles that drive the Spa­tialite back­end (see file for­mat docs). These ta­bles can be housed in any schema, but we use map_digitizer by de­fault.

Post­GIS with man­aged topol­ogy

The most ro­bust way to run a fully fea­tured map­ping server for work with Map­board GIS is to use the Post­GIS Ge­o­logic Map topol­ogy watcher. This soft­ware man­ages the topol­ogy of a ge­o­logic map it­er­a­tively, in­de­pen­dent of the choice of GIS plat­form for mak­ing ed­its.

Post­GIS Ge­o­logic Map is de­signed to be testable, val­i­dated, and per­for­mant, and it serves as the ba­sis for ad­vanced topo­log­i­cal op­er­a­tions within Map­board GIS. Al­though the solver is ag­nos­tic to in­put GIS en­vi­ron­ment, the Map­board server ex­ten­sions are bun­dled by de­fault.

Post­GIS Ge­o­logic Map adds to the map_digitizer schema that tracks core map ed­its with a map_topology schema that or­ga­nizes the solved topo­log­i­cal re­la­tion­ships that make up the map. This schema can be re­gen­er­ated at will, but pro­gres­sively up­dat­ing its ta­bles serves as the ba­sis for the it­er­a­tive map edit­ing show­cased in Map­board GIS.

In­stalling the server com­po­nents

Since both Post­GIS Ge­o­logic Map (pre­ferred) and the core Map­board server ex­ten­sions are server-side soft­ware, in­stalling and con­nect­ing to them can be dif­fi­cult. Both pro­jects can be built from source by down­load­ing the code from GitHub. Both can be in­stalled lo­cally or us­ing Docker to man­age the con­tainer­ized app, in­clud­ing the req­ui­site data­base server.

For Post­GIS Ge­o­logic Map, the pre­ferred server im­ple­men­ta­tion, in­stal­la­tion is well-cov­ered in the README. The gist of cre­at­ing a Docker-man­aged build (with test data) is as fol­lows:

1. Make sure Docker and docker-compose are in­stalled us­ing the in­struc­tions for your plat­form.
2. Mod­ify the docker-assets/docker-map-config.json con­fig­u­ra­tion file to suit your needs (typ­i­cally, this in­volves chang­ing the srid and tolerance fields). A bet­ter way to con­fig­ure the ap­pli­ca­tion in Docker is forth­com­ing.
3. Run docker-compose up --build. No need for a lo­cal Post­greSQL in­stal­la­tion!
4. Con­nect to the geologic_map data­base on lo­cal port 54321 us­ing your GIS soft­ware or data­base client.

{
  "app": "mapboard-server",
  "version": "2.0.0",
  "projection": {
    "srid": 32733,
    "auth": "EPSG:32733",
    "description": "WGS 84 / UTM zone 33S",
    "projected": true,
    "proj4": "+proj=utm +zone=33 +south +datum=WGS84 +units=m +no_defs "
  },
  "topology": {
    "name": "map_topology",
    "srid": 32733,
    "precision": 0.1
  },
  "backend": "PostGIS",
  "capabilities": [
    "basic-editing",
    "reshape",
    "topology",
    "select-features",
    "topological-line-erase"
  ]
}

Once you’ve started the ap­pli­ca­tion, the Map­board server should be run­ning lo­cally on your com­puter. By de­fault, the server is ex­posed on port 3006. You can ver­ify this by nav­i­gat­ing to http://localhost:3006/meta in your browser. You should see a REST API re­sponse much like the one be­low:

This means you’ve suc­cess­fully in­stalled the Map­board server! If you’re us­ing the server with­out the Post­GIS Ge­o­logic Map ex­ten­sions, the capabilities ar­ray will con­tain fewer en­tries. This tells Map­board GIS to dis­able the cor­re­spond­ing func­tion­al­ity.

Con­nect­ing

The next step is con­nect­ing to the server from Map­board GIS. If you are run­ning the ap­pli­ca­tion on a pub­licly ad­dress­able ma­chine, the server will be avail­able at <your-server-address>:3006. Oth­er­wise you have to find your IP ad­dress or lo­cal net­work ad­dress. On Ma­cOS this is done in the Shar­ing panel of Sys­tem Pref­er­ences. Al­ter­na­tively, the raw IP ad­dress can be found us­ing the com­mand ipconfig getifaddr en0 (on Mac and Linux plat­forms). Win­dows users, you’re on your own for now, sorry!

Once you have the proper con­nec­tion string (e.g., Daven-Quinn.local:3006), you can con­nect in Map­board GIS at the pro­ject cre­ation/​edit­ing in­ter­face. When the pro­ject is loaded, the app will be­gin talk­ing to the server at that ad­dress to load linework and han­dle edit­ing.