Example: Import GeoJSON File

In this example we use Manifold's GeoJSON dataport to import vector footprints for all buildings in the District of Columbia, using a GeoJSON file published as open data by Microsoft.


GeoJSON is a text-based format written in JavaScript Object Notation (JSON) that is sometimes used for interchange of vector data.   It is often is found in files with a file name extension of .geojson or, occasionally, a file name extension of .json.  When GeoJSON files use the .json extension that can cause confusion, since non-geo JSON files ending in .json are often used to convey non-spatial format, or to convey spatial format in tabular, not spatial form.


When files containing GeoJSON data end in a .json extension, we can still import them as GeoJSON files, but we must tell Manifold to use the GeoJSON dataport and not the JSON dataport.  


Microsoft has recently published vector footprints of over 125 million buildings in the US in GeoJSON format under the Open Data Commons Open Database License (ODbL). However, Microsoft's files all use the .json file name extension instead of .geojson.   No problem, as it is easy to import them all as GeoJSON.


Important: The GeoJSON dataport's limitation to 2 GB currently disallows use of Microsoft's Texas and California files, both of which are larger than 2 GB.    This limitation will be removed in upcoming builds, allowing use of these and other GeoJSON files that exceed 2 GB.  Until then, if we really want to use those files, we can use a text editor to split them into two or more parts, each of which is under 2 GB.   We import those as separate drawings, and then we use Edit - Merge to combine them into a single drawing.


We will import a .json file that provides vector footprints of buildings in the District of Columbia.  This is part of the collection of all US building footprints recently published as open data by Microsoft on their US Building Footprints page on Github.    Microsoft publishes files as .zip files.  Unzip the file to get the .json file.  


To fit into this documentation, illustrations show an artificially small Manifold desktop, with only a few panes, docked to the right side.   In real life we use a much larger Manifold desktop, and all panes would be turned on, with some panes docked to the left and others docked to the right.



Choose File - Import.  



Navigate to the desired .json or .geojson file and click it.   In this case, Microsoft publishes GeoJSON data using a file extension of .json, so we will first choose the file and then in the next step specify the GeoJSON dataport should be used.



Next, in the file type box we choose GEOJSON Files (*.geojson).   The dialog display clears, since there are no files with a .geojson extension in the folder, but the name of the file we want remains in the File name box.   


Press Import.



The file imports as a drawing and the drawing's table.   Double-click the drawing to open it.  



Zooming into the drawing we can see the building footprints as areas, styled in default gray format.  We can see from the Status Bar's Scale and Position readouts the drawing is correctly positioned and scaled.



Back in the Project pane we can double-click open the drawing's table. We can see that this particular data set from Microsoft has only one field, the geometric shape for each vector object, all of which are areas.

Create a Map with a Bing Background

Basically, we have done what we have set out to do: we have imported a .json file provided by Microsoft.   But more interesting is using the drawings to create more useful displays.   


We will next create a map, with two layers providing cool backgrounds from Microsoft's Bing satellite and street map servers.    Those extra layers will make it easier to understand what we see in the drawing imported from the .json file.



We create a new map by choosing File - Create - New Map.



In the New Map dialog we choose Bing Maps Street Map as the Base layer.  We check the box for the DistrictofColumbia Drawing to include that drawing as a layer in the map.  Press Create Map.



That creates a new map in the project, with the drawing as a layer and a base layer using the Bing streets web server.  The New Map dialog automatically creates a Bing streets data source, to provide the base layer.


The drawing is just a small part of the map, which is zoomed out to the entire world, so we Ctrl-click the drawing's layer tab to zoom to that layer.



As we zoom in, the Bing street map server automatically fills in the base layer image.

Create an Additional Web Server Layer

In addition to the Bing streets layer, we would also like to add a Bing satellite layer to the map.


We add a Bing satellite data source to the project by choosing File - Create - New Data Source.



The Bing Maps Satellite image server is one of the default Favorites listed in the menu, so we can pick it with a single click.



We expand the Bing Maps Satellite data source.



That shows the Bing Maps Satellite Image layer that we want to drag and drop into the map.  


Before we do that, we take a moment to click the Bing streets layer tab to make that tab the active layer.  Whatever layer we drag and drop into the map will appear just above whatever is the active layer.  We make the Bing streets layer the active layer so the satellite layer will drop into the display stack just above it.



We drag and drop the Bing Maps Satellite Image layer into the map.



The Bing satellite layer appears in the map.   We do not need it right away, so we double-click the layer tab to turn that layer off.


We will zoom into downtown Washington.



We right-click and drag to draw a zoom box, to zoom to that box.   

 Basic navigation:  the default mouse mode in Manifold is navigation.  Using the left mouse button we can click and drag to pan the display.  Using the right mouse button we right-click and drag to draw a zoom box to zoom to that box.   The wheel on a wheel mouse zooms in and out.



Zoomed further into the view we see that the drawing imported from the .json shows building footprints as areas, displayed in default, gray formatting.

Style the Drawing

We can create a more appealing and more legible display by coloring areas in the District of Columbia drawing.


We zoom further into the map, and then we click the DistrictofColumbia layer to make it the active layer.  Next, we use the Style pane, seen below as an undocked pane,  to choose a blue color for fill color for areas.   



Some GIS packages allow only a single object type, such as only areas, in a layer.  Manifold allows a mix of areas, lines and points in drawings, so the Style pane provides controls for foreground color, fill color, symbology, and size for areas, lines and points, plus a rotation factor for point icons and area hatch patterns.



We turn the satellite layer back on.   We can do that either by double-clicking the Bing satellite layer tab to turn it on, or we can use the Layers pane.



We will use the Layers pane.  We click on the Layers pane tab and then we click on the Bing satellite layer.  It immediately appears.


To better see how building footprints align to buildings that are visible in the satellite photo view, we can change the style used to show areas.



Back in the Style pane we change area foreground color, used for area borders, to bright green.  We change area fill color to transparent color, indicated by a hatch pattern.    The result is that areas appear only as bright green outlines with no fill color.



To get a larger display, to make better use of the small screenshot sizes used in this documentation, we can undock the map window.  Shift-click the title tab for a window or a pane to undock it.



 Much better!   We can now move and resize the undocked map window, to get a bigger view of what is in the map.



Zooming in we can see alignment is not bad but is far from perfect.  The image above changes style slightly to apply a hash pattern to the areas.  Yes, that is a number 1 on the grass.  See Notes below.


Microsoft created the vector data set of building footprints using an automated process, by grinding the entire US database of Bing images through a neural network, using AI techniques to find buildings and to then clean up the resultant polygons.  



A few minutes of looking about in the District of Columbia indicate numerous errors.   For example, the scene above shows the region near the Washington Monument.



Zooming into the WWII memorial we see the automated process identified part of the reflecting pool between the monument and the Lincoln Memorial (out of view to the left) as a building.  The process also identified parts of the plaza as buildings.




The process also identified buildings in open grassy areas in the park to the South, although it correctly located one building in the view above.

More Colorful Style

If we like, we can use the Style pane to do a thematic format to apply many colors to the drawing.   The following technique depends on having an mfd_id key field and index in the drawing.  Current builds that import GeoJSON do not automatically add an mfd_id index.  This will be added soon, given that GeoJSON might become popular as an interchange format.  In the interim, it takes but a moment to add an mfd_id key field and index to the drawing's table as described in the Add an Index to a Table topic.



In the Style pane we add a thematic format using the mfd_id field as seen above.  We use a method of equal intervals, tallied to 16 breaks.  We have applied the CB Paired palette, one of the fine Color Brewer palettes available by default with a point and click.



The result is a more colorful display of building footprints in the District of Columbia.  


Download Microsoft's Data - We can download Microsoft's data from their US Building Footprints page on Github.   Thank you, Microsoft!


Is that a number one on the lawn?  - Yes, one of the illustrations above, showing green hatched building outlines with a satellite layer background really does show a large number 1 on the lawn.



We can see it better by adding a Google satellite layer, which has better resolution in Washington than Bing, and zooming in.   The number is located on the lawn of President's Park, at the corner of 17th Street NW and E Street NW, as we can tell by zooming out a bit, turning off the Google satellite layer and turning on the Bing Streets layer.



We have turned on the building footprints drawing layer as well, in the illustration above.  Using multiple web server layers is a great way to instantly get more information about what we see in a particular view.



Turning the Google satellite layer back on and zooming slightly in from the preceding view, we see a monument with a tall column towards the Northern side of the small park.  That is the First Division Monument, erected in 1924 to honor the 1st Infantry Division of the US Army.    Although the National Park Service's web site does not describe the large 1 in the lawn, it is likely a safe guess that the number also memorializes the First Division.  The curved, smaller road on the right edge of the image is part of the White House grounds.



See the video version of this topic in the Manifold 9 - Microsoft JSON Building Footprints video.


See Also







Web Servers


File - Import


File - Create - New Data Source