- "markdown": "---\ntitle: \"Get started with GRASS in Jupyter Notebooks on Windows\"\nauthor: \"Caitlin Haedrich\"\ndate: 2024-06-15\nimage: images/getting_started_grass_jupyternotebook.png\ndate-modified: today\nformat:\n html:\n toc: true\n code-tools: true\n code-copy: true\n code-fold: false\ncategories: [Python, Windows, beginner]\ndescription: Learn how to run GRASS in Jupyter Notebooks on Windows.\nengine: jupyter\nexecute:\n eval: false\njupyter: python3\n---\n\n\n\nThe development of the Python package `grass.jupyter`, has streamlined the use \nof GRASS GIS is Jupyter notebooks. In this tutorial we will demonstrate the \nrecommended way of running GRASS GIS in Jupyter Notebooks for Windows users.\n\n## Set Up\n\nOn Windows, we'll use the OSGeo4W package manager to setup and update GRASS GIS,\nJupyterlab and other dependencies. Follow the directions below to setup Jupyter \nand GRASS in Windows.\n\n#### 1. Download the OSGeo4W Network Installer\n\nDownload the OSGeo4W network install from [here](https://trac.osgeo.org/osgeo4w/). \nOpen it and select _\"Advanced Install\"_.\n\n#### 2. Install GRASS GIS, Jupyterlab and `grass.jupyter` dependencies\n\nFollow the prompts until you get to the _\"Select Packages\"_ window (the defaults\nare fine for most situations). Use the Search bar to find and select the \nfollowing packages for install (switching from \"Skip\" to the version number):\n\n* `grass`\n* `python3-jupyterlab`\n* `python3-ipywidgets`\n\n{width=60%}\n\n#### 3. Go make a cup of tea\n\nIt may take a minute to install... Click \"Finish\" and exit when it finishes.\n\n#### 4. Open the OSGeo4W Shell and install folium\n\nLaunch the OSGeo4W Shell and install folium with:\n\n`pip install folium`\n\n#### 5. Launch Jupyter Lab\n\nWe're ready to launch jupyterlab now: \n\n`jupyter lab`\n\n\nThis should launch Jupyter lab in your default web browser. Use the left side\npanel to navigate to the notebook you wish to run and you're ready to go!\n\n#### 6. Launching Jupyter Lab in the Future\n\nTo launch Jupyter Lab in the future:\n\n1. Open the OSGeo4W Shell\n2. Launch jupyter lab with `jupyter lab`\n\n\n## Start GRASS within Jupyter\n\nNow, we're ready to code! Let's import the GRASS GIS Python packages and launch\nGRASS GIS. If you want to run this tutorial, please download and unzip the \nNorth Carolina [sample dataset](https://grass.osgeo.org/sampledata/north_carolina/nc_spm_08_grass7.zip).\n\n::: {#eb33679f .cell execution_count=1}\n``` {.python .cell-code}\n# Import standard python packages\nimport sys\nimport subprocess\n\n# Ask GRASS GIS where its Python packages are and add them to the path\ngrass_call = \"grass83\"\nsys.path.append(\n subprocess.check_output([grass_call, \"--config\", \"python_path\"], text=True, shell=True).strip()\n)\n\n# Import the GRASS GIS python packages we need\nimport grass.script as gs\nimport grass.jupyter as gj\n\n# Launch a GRASS GIS session.\ngj.init(\"path/to/nc_spm_08_grass/user1\");\n```\n:::\n\n\n## Using GRASS\n\nNow that we have GRASS GIS running in our notebook, let's try some basic \ncommands. \n\nIn this section, we will set the color table to the `elevation` raster map from\nthe GRASS GIS sample project we downloaded and then display it. \n\n::: {#886b7cfb .cell execution_count=2}\n``` {.python .cell-code}\n# Set the computational region to the study area\ngs.parse_command(\"g.region\", \n raster=\"elevation\", \n flags='pg')\n\n# Set colors for elevation raster\ngs.run_command(\"r.colors\", \n map=\"elevation\", \n color=\"elevation\")\n```\n:::\n\n\n::: {#1e8076e1 .cell execution_count=3}\n``` {.python .cell-code}\n# Create Map instance\nimg = gj.Map()\n# Add a raster\nimg.d_rast(map=\"elevation\")\n# Add legend\nimg.d_legend(raster=\"elevation\", at=(55, 95, 80, 84), flags=\"b\")\n# Display map\nimg.show()\n```\n:::\n\n\nNow, we're up and running! Have a look at other tutorials for inspiration on \nthe avenues you can follow with GRASS tools combined with other Python packages. \n\n## Troubleshooting\n\nSomething not working? Here are some common stumbling blocks...\n\n* `FileNotFoundError`\n\n::: {#8941a14a .cell execution_count=4}\n``` {.python .cell-code}\nFileNotFoundError: [WinError 2] The system cannot find the file specified\n```\n:::\n\n\nCheck the `shell` parameter in the `subprocess.check_output()`. On Windows, \nthis should be `shell=True`. On Mac and Linux operating systems, this should \nbe `shell=False`.\n\n* `CalledProcessError`\n\n::: {#d53ea2c4 .cell execution_count=5}\n``` {.python .cell-code}\nCalledProcessError: Command '['grass83', '--config', 'python_path']' returned non-zero exit status 1.\n```\n:::\n\n\nCheck which version of GRASS GIS you have installed. On Windows, the `grass_call`\nshould be `grass` followed by the first two digits of the version you have \ninstalled (for example, GRASS GIS 8.4 would be called with `grass84`). On Mac and \nLinux, it should be just `grass`.\n\n* Errors from `gj.init()`\n\nThis command takes several different configurations of the GRASS GIS project \nand mapset location on your system. All the following are examples that work:\n\n```\ngj.init(\"path/to/grassdata\", \"project_name\", \"mapset_name\")\ngj.init(\"path/to/project_name/mapset_name\")\ngj.init(\"../project_name/mapset_name\")\n```\n\nAlso pay attention to the slash direction. Windows uses `\\` in it's file \npaths but the `\\` character in strings is also for escaping characters (for\nexample, putting `\\n` in a string will print a new line). Therefore, you'll \nneed to either switch to forward slashes (`/`) or put double back-slashes \n(`\\\\`).\n\n",
0 commit comments