Improved Integration of GRASS and Jupyter

Start GRASS GIS

import os
import subprocess
import sys

# Ask GRASS GIS where its Python packages are.
sys.path.append(
    subprocess.check_output(["grass", "--config", "python_path"], text=True).strip()
)

# Import GRASS packages
import grass.script as gs
import grass.jupyter as gj

# Start GRASS Session
session = gj.init("../../data/grassdata", "nc_basic_spm_grass7", "user1")

# Set computational region to the elevation raster.
gs.run_command("g.region", raster="elevation")

GRASS Renderer

The GrassRenderer class creates and displays GRASS maps as PNG images. There are two ways to add elements to the display. First, the name of the GRASS display module can be called as an attribute by replacing the "." with "_" in the module name. For example:

m = GrassRenderer()
m.d_rast(map="elevation")

Alternatively, GRASS display modules can be called with the run() method:

m = GrassRenderer()
m.run("d.rast", map="elevation")

To display the image, call show().

# Create GrassRenderer instance
img = gj.GrassRenderer()

# Add a raster, vector and legend to the map
img.d_rast(map="elevation")
img.d_vect(map="streams")
img.d_legend(raster="elevation", at=(55, 95, 80, 84), flags="b")

# Display map
img.show()

We can also have multiple instances of GrassRenderer. Here, we create another map then go back and modify the first map.

# Make a second instance.
# Just for variety, we'll make this one a different size
img2 = gj.GrassRenderer(height=200, width=220)

# Add a some layers
# We can also add layers with the run() methods
img2.run("d.rast", map="elevation_shade")
img2.run("d.vect", map="roadsmajor")

# Display second map
img2.show()

# Then, we return to the first instance and continue to modify and display it
# Notice that layers a drawn in the order they are added
img.run("d.vect", map = "zipcodes", color="red", fill_color="none")
img.show()

By default the display extent (and resolution if applicable) is derived from the first raster or vector layer:

img3 = gj.GrassRenderer()
img3.d_vect(map="boundary_state")
img3.d_rast(map="geology")
img3.show()

To respect computational region, set use_region=True:

img4 = gj.GrassRenderer(use_region=True)
img4.d_vect(map="boundary_state")
img4.d_rast(map="geology")
img4.show()

You can also use a saved region:

gs.run_command("g.region", save="myregion", n=224000, s=222000, w=633500, e=637300)
img5 = gj.GrassRenderer(saved_region="myregion")
img5.d_rast(map="elevation")
img5.d_rast(map="lakes")
img5.show()

GRASS 3D Renderer

The Grass3dRenderer class creates 3D visualizations as PNG images. The m.nviz.image module is used in the background and the function render() accepts parameters of this module. The Grass3dRenderer objects have overlay attribute which can be used in the same way as GrassRenderer and 2D images on top of the 3D visualization. To display the image, call show().

First, let's create the object:

img = gj.Grass3dRenderer()

Now, render a 3D visualization of an elevation raster as a surface colored using, again, the elevation raster:

img.render(elevation_map="elevation", color_map="elevation", perspective=20)

To add a raster legend on the image as an overlay using the 2D rendering capabilities accessible with overlay.d_legend:

img.overlay.d_legend(raster="elevation", at=(60, 97, 87, 92))

Finally, we show

img.show()

Now, let's color the elevation surface using a landuse raster (note that the call to render removes the result of the previous render as well as the current overlays):

img.render(elevation_map="elevation", color_map="landuse", perspective=20)
img.show()

Switching Mapsets and Session Management

The init function returns a reference to a session object which can be used to manipulate the current session. The session is global, i.e., the global state of the environment is changed. The session object is a handle for accessing this global session. When the kernel for the notebooks shuts down or is restarted, the session ends automatically. The session can be explicitly ended using session.finish(), but that's usually not needed in notebooks.

Additionally, the session object can be used to change the current mapset. Here, we will switch to mapset called PERMANENT:

session.switch_mapset("PERMANENT")

Now we could add more data to the PERMANENT mapset or modify the existing data there. We don't need to do anything there, so we switch back to the mapset we were in before:

session.switch_mapset("user1")