Map View with GeoJSON Files and Custom Maps

Using GeoJSON Files and Custom Maps in Map View

⚠️ Feature in development: This feature is in development and is not yet available on the main MicrobeTrace site.

GeoJSON Files and custom maps support three types of tasks:

1. Add latitude and longitude coordinates to existing nodes.
2. Add addtional geographic data to an existing map or as a standalone map.
3. Replace a map with an image, such as a floorplan, and place nodes on it.

Use case 1: Add latitude and longitude coordinates to nodes

Use this workflow when a GeoJSON file contains locations for nodes that are already in MicrobeTrace.

Before you begin

• Each GeoJSON feature must have an ID that matches an existing node ID.
• Coordinates must use GeoJSON order: [longitude, latitude].
• The GeoJSON file adds locations to existing nodes; it does not create new nodes.

Steps

1. Open the Files tab.
2. Add the GeoJSON file along with your node data.
3. Confirm that the file type is GeoJSON.
4. In the GeoJSON file's ID selector, choose the property that matches the node IDs.
5. Select Launch for a new dataset or Update if the dataset is already open.
6. Open Map View.

For each match, MicrobeTrace adds GeoJSON Latitude, GeoJSON Longitude, and GeoJSON Feature ID to the node. It also selects the new latitude and longitude fields for Map View.

The example example_node_locations.geojson works with the preloaded dataset.

If nodes do not move, confirm that the selected GeoJSON ID property exactly matches the node IDs.

Use case 2: Display a GeoJSON custom map

Use this workflow when you want to display and/or higlight GeoJSON elements such as state, county, campus, or building boundaries. Uploading GeoJSON here displays it as a map but does not add its properties or coordinates to nodes.

(https://github.com/CDCgov/MicrobeTrace/blob/dev/examples/example_files/selected_states.geojson?short_path=eeab830) Download Example File

Download Example File 2 Download Example File 3 Download Example File 4 Download Example File 5 MicrobeTrace/dev/examples/example_files/selected_states.geojson

Steps

1. Load your data and open Map View.
2. Open Settings > Custom Map.
3. Under Background, select a .geojson or .json file.
4. Choose how to display the Layer:
   • Show displays the custom map by itself and hides the standard map layers.
   • Overlay displays the custom map over the selected basemap or other standard map layer.
   • Hide temporarily hides the custom map without removing it.
5. Select Center to fit the custom map and nodes on the screen.

You can also change the GeoJSON Color, Transparency, and Labels in the same settings panel.

This use case can be used to highlight specific regions, add additional map boundary (such as state boundaries for Brazil), or add additionally geographic data (such as New York Subway System) to the map.

Use case 3: Display an image or floorplan

Use this workflow to place nodes on a non-geographic image such as a floorplan, seating chart, or diagram. Common supported formats include .png, .jpg, .jpeg, .gif, .webp, and .svg.

Prepare the node data

If you want MicrobeTrace to place groups of nodes into labeled areas, first add a field containing the area name for each node, for example, Room. For your own dataset, this field can just be added to the node list.

The example COVID-19_simulated_testFloorplan.csv adds room numbers to nodes in the preloaded dataset. Add it on the Files tab and select Update before opening Map View.

Add the floorplan

1. Open Map View > Settings > Custom Map.
2. Under Background, select an image. For example, use example_floorPlan.png.
3. Set Layer to Show.
4. Select Center.

You can now place nodes with room boundaries, manual positioning, or both.

Place nodes by room or area

This is the quickest method when multiple nodes share a room or other labeled area.

1. Under Boundary Labels, set Node Field to the field containing the room or area names. For the example data, select Room.
2. Select Polygon or Freehand, then draw the boundary of one room on the image.
3. Enter a label that matches a value in the selected node field, such as 1-101.
4. Select Save.
5. Repeat for the remaining rooms.

MicrobeTrace places each matching node within its labeled boundary. The Status line shows how many nodes are matched and unmatched.

Place nodes manually

Use this method to choose the exact position of individual nodes.

1. Under Manual Positions, set Positioning to On.
2. Choose a node from the Node dropdown.
3. Select the desired location on the image.
4. Select Next Unplaced and repeat as needed.

You can also drag a placed node to move it. A manual position takes priority over a position created from a room boundary.

Helpful controls

• Clear removes the current custom map. For an image, it also removes its saved boundaries and boundary-generated positions.
• Clear Selected removes the selected node's manual position.
• Clear All removes all manual positions for currently visible nodes.
• Reposition All assigns new positions within the saved boundaries.
• Saving the session as a .microbetrace file preserves the custom map, boundaries, and node positions.

Quick troubleshooting

• A GeoJSON feature did not match a node: Check the ID property selected on the Files tab and confirm that its values exactly match the node IDs.
• Nodes do not appear on a GeoJSON map: Confirm that the nodes have valid latitude and longitude values.
• Nodes do not appear on a floorplan: Confirm that the layer is set to Show and either define matching room boundaries or place the nodes manually.
• A room has unmatched nodes: Confirm that the boundary label matches the node field value. Matching ignores capitalization and spaces at the beginning or end.