TouchTerrain_jupyter_starters_binder.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# TouchTerrain jupyter notebook - starter edition, running on Binder\n",
    "Chris Harding, Aug. 25 , 2022 (<charding@iastate.edu>)\n",
    "\n",
    "Warning: This is still being tested! Please report bugs to me.\n",
    "\n",
    "- This particular notebook is meant to be run on Binder (which uses JupyterLab). \n",
    "- It is also primarily aimed at users who maybe new to Python and jupyter. It walks through the process of using TouchTerrain to create STL files for 3D printing with many small steps at a slow pace, makes few assumptions and gives more explanations.\n",
    "- Hopefully this will make the much more flexible and powerful __standalone version__ of TouchTerrain accessible to many more users!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Preparing to use Google Earth Engine online DEM rasters \n",
    "\n",
    "- TouchTerrain uses Digital Elevation Data (DEM)\n",
    "- You can either use online elevation data or a local elevation dataset (geotiff file)\n",
    "- *You don't need to go through this preparation part if you only want to use terrain data from locally stored raster files (geotiffs)*. You will get a warning about EE not being initialized properly but you can ignore that. Instead go directly to __How to run code inside a notebook__\n",
    "- TouchTerrain can use DEM data from Google Earth Engine (given the corners of the area), but you need to first set up an earth engine account and create Google cloud project. Note that this includes setting up a charge account, however, you will typically not be charged. \n",
    "- See this [guide](https://github.com/ChHarding/TouchTerrain_for_CAGEO/blob/master/EarthEngine_authentication_guide.md#request-a-earthengine-dev-account) for how to get an earth engine account.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### How to run code inside a notebook\n",
    "\n",
    "- Below is a python *code* cell.\n",
    "- Run the cell  by clicking inside it and pressing Shift + Enter. Or you can hit the triangle Run button.\n",
    "- You wont see any output for this cell but you'll see that the braces in `In [ ]` will show a sequential number, which means it's been run."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ee # import module for earthengine-api "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Authentication with Earth Engine\n",
    "- the next cell will initiate an authorization with the earth-engine. \n",
    "- remove the leading `#` (uncomment the line) and run it. Make sure there's no space in front of ee!\n",
    "\n",
    "<div>\n",
    "\n",
    "- This text should appear and you should be redirected to a webpage:\n",
    "```\n",
    "To authorize access needed by Earth Engine, open the following URL in a web browser and follow the instructions. If the web browser does  not start automatically, please manually browse the URL below.\n",
    "```\n",
    "- The web page will have you select a Google account for use with Earth Engine and give you a token\n",
    "- Assuming you got your earth engine account, follow [this part of the guide](https://github.com/ChHarding/TouchTerrain_for_CAGEO/blob/master/EarthEngine_authentication_guide.md#generating-the-token) to get this token\n",
    "- Paste in your token here: `Enter verification code: <your token>` and hit Enter, you should get `Successfully saved authorization token.`\n",
    "- Important: this needs to be done only once after the binder instance was created (as it just needs to create a file). Once done, you should put the `#` back in front of ee.Authenticate() (so the line is `#ee.Authenticate()` again), so you're not running it again after you've started from top after a kernel timeout."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "#ee.Authenticate() # authenticate your earth engine to consume DEM data from Google"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### What to do when then kernel times out (quits)\n",
    "- The python kernel is the underlying python interpreter that runs the python code when you execute a code cell\n",
    "- When the notebook is idle for a while (maybe you're somewhere in the middle of the notebook), it seems that its kernel will time out.\n",
    "- You'll see `kernel disconnected` at the bottom and `No Kernel` at the upper right. \n",
    "- This means you can't run the next code cell but have to reconnect to the kernel first\n",
    "- Click on `No Kernel` at the upper right, select the Python kernel and the click on Select\n",
    "- You should now be able to again execute code cells\n",
    "- Sometimes however, you may have to restart the kernel instead (Top Menu - Kernel - Restart and clear outputs)\n",
    "- In this case you need to again start from the top of the notebook. Note however, that you don't have to go through the authorization again if you completed it once, so make sure this line is commented out!\n",
    "- Finally, if you ever get Error 405 when Starting the Kernel I'm guessing the binder instance has died due to timeout. You will need to close your current browser page and go to https://mybinder.org/v2/gh/ChHarding/TouchTerrain_for_CAGEO/HEAD?labpath=TouchTerrain_jupyter_starters_binder.ipynb again to create a new Binder instance. This will again take some time but less then the very first time (at least in my experience)\n",
    "- This also means that any STL files you may have created earlier are lost, so it is important to download them right away."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Virtual python environment \n",
    "- this is just FYI, don't worry if you don't know what conda is ...\n",
    "- binder will create a virtual conda environment called *notebook* and install all the package from environment.yml in it (which takes a while)\n",
    "- the first part in environment.yml ensures that geemap can run properly as apparently the install order and version matter, the rest will install all other dependencies for touchterrain\n",
    "- binder will the run a shell script called postBuild, which will use pip to install the touchterrain package\n",
    "- binder runs the current notebook within this *notebook* environment, so the imports below should all work"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Importing python packages\n",
    "- Run the next cell, it'll import the required packages into Python, including Touchterrain\n",
    "- The earth engine package you imported and authorized earlier, will be initialized here. You should see `EE init() worked with .config/earthengine/credentials`\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# import packages\n",
    "import os.path\n",
    "from glob import glob\n",
    "import k3d\n",
    "from random import randint\n",
    "from shutil import rmtree\n",
    "import zipfile\n",
    "from geojson import Polygon\n",
    "import geemap\n",
    "from touchterrain.common import TouchTerrainEarthEngine as TouchTerrain\n",
    "from touchterrain.common.TouchTerrainGPX import *\n",
    "args = TouchTerrain.initial_args # default args"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Define the values for processing settings\n",
    "- We now need to define the processing settings for the 3D model we want to create. Unlike the web app, they need to be set via Python variables.\n",
    "- The variable `args` will hold all processing settings. The __name__ of a setting  will be between [] and inside double quotes, the setting's __value__ will be to the right of the = . The value can be a number (120 or 0.4), a string (\"STLb\") or the special value `None`.\n",
    "- Example: `args[\"tilewidth\"] = 120`     will define the value of the setting named `tilewidth` to be 120\n",
    "\n",
    "### Comments\n",
    "- In Python, anything to the right of a `#` will be ignored.\n",
    "- You will often need comment out or uncomment a line of Python code.\n",
    "- A line starting with a `#` (no spaces before it) is said to be commented out, it will be entirely ignored. This a useful to temporarily deactivate the line and re-activate it again later.\n",
    "- To uncomment a line means to remove the leading `#`, again leaving no spaces before the first actual code letter. This makes the line valid code again.\n",
    "\n",
    "<div>\n",
    "\n",
    "- Example of commenting out a line of code and uncommenting it properly:\n",
    "```\n",
    "print(123)\n",
    "#print(123)\n",
    "print(123)\n",
    "```\n",
    "- Examples of bad commenting with a leading space. I'm using an underscore here for better visibility.\n",
    "```\n",
    "_#print(123)\n",
    "_print(123)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Use a locally stored geotiff DEM file instead of an online DEM\n",
    "__If you don't plan to use a local geotiff and instead want to use an online DEM, skip this cell and go to *Select your print area*__\n",
    "- You may want create a terrain model from a geotiff DEM file that you've downloaded or created via a GIS. As TouchTerrain needs to import this file during processing, you first need to copy (upload) it via the jupyterLab File Manager.\n",
    "- Open the File Manager (left side) and drag your geotiff into the panel to upload it. Remember the file name for later\n",
    "- The folder called __stuff__ contains a very small example geotiff file called __pyramid.tif__. From the (root) folder this notebook is in, the path to this file is therefore __stuff/pyramid.tif__  \n",
    "\n",
    "<div>\n",
    "\n",
    "- The cell below sets the value of __importedDEM__ to this path (e.g. `\"stuff/pyramid.tif\"`). To use your geotiff file, replace this with it's name, e.g. `\"myDEM.tif\"` (make sure to use \"s!). \n",
    "- if you do NOT want to use a local geotiff and want to use online DEM rasters instead, set the value to None. Comment/Uncomment the appropriate choice below and hit Shift-Enter\n",
    "- if you are using a local geotiff, skip _Select DEM source_ and _Select print area on geemap_ as the geotiff is your DEM source and  implicitly defines the print area. Go straight to _Setting the tile width_"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Comment out one of following two lines:\n",
    "#args[\"importedDEM\"] =  \"stuff/pyramid.tif\" # path of local geotiff file to use\n",
    "args[\"importedDEM\"] = None  # no file used, use online DEM rasters instead\n",
    "\n",
    "# convert into an absolute path for later\n",
    "if args[\"importedDEM\"] != None:\n",
    "    args[\"importedDEM\"]= os.path.abspath(args[\"importedDEM\"]) \n",
    "    print(\"importedDEM\", args[\"importedDEM\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Select the name of the DEM source (online elevation data)\n",
    "- Before you can select the actual print area, you need to select which online DEM source will be used. The setting is called `DEM_name`.\n",
    "- There are several options but for starters you only need to decide among two options:\n",
    "    - If your area is in the lower 48 US states, use `USGS/NED`\n",
    "    - Anywhere else on the globe use: `JAXA/ALOS/AW3D30/V2_2`\n",
    "    - (there are more DEM sources to choose from, see `DEM_name` [here](https://github.com/ChHarding/TouchTerrain_for_CAGEO#processing-parameters) )\n",
    "- Comment/uncomment the appropriate line in the cell below and hit Shift-Enter"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Comment out one of the following two lines\n",
    "args[\"DEM_name\"] = \"USGS/3DEP/10m\"  # area is within the lower 48 (US)\n",
    "#args[\"DEM_name\"] = \"JAXA/ALOS/AW3D30/V2_2\"  # area is outside the US (worldwide)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Import GPX path lines\n",
    "__This is more of an expert option. If you are just starting, skip this and go to the next cell__\n",
    "- You can drape one or more gpx (path) files over your terrain\n",
    "- Similar to importedDEM, the file names for the GPX file(s) are stored in the importedGPX setting.\n",
    "- However, as you can import more than one GPX file, you need to put the path name into a list, i.e. inside brackets, even if you just have one GPX file. Separate multiple GPX files with a comma:  \n",
    "    - `args[\"importedGPX\"] = [\"justonegpxfile.gpx\"]`  \n",
    "    - `args[\"importedGPX\"] = [\"file1.gpx\", \"file2.gpx\"]`\n",
    "- `gpxPathHeight` (in meters) defines how much a path is elevated above the terrain. Use a negative number to create a trench.\n",
    "- `gpxPixelsBetweenPoints` (in meters) lets you reduce the number of point in your path to place a point only every X meters. This can help to simplify complex patterns.\n",
    "- `gpxPathThickness` (meters) controls the thickness of the path, which makes it more pronouced when printed\n",
    "- There are several GPX example files in the stuff folder. To use them, uncomment the first 4 lines in the cell below and comment out the last line.\n",
    "- If you're not using GPX files, just leave the cell as is and run it. Setting importedGPX to None means that no GPX files are imported.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "args[\"gpxPathHeight\"] = 5\n",
    "args[\"gpxPixelsBetweenPoints\"] = 20\n",
    "args[\"gpxPathThickness\"] = 2\n",
    "\n",
    "# Comment out one of the following two lines\n",
    "#args[\"importedGPX\"] = [\"stuff/gpx-test/DLRTnML.gpx\", \"stuff/gpx-test/DonnerToFrog.gpx\", \"stuff/gpx-test/CinTwistToFrog.gpx\"] # list of GPX files\n",
    "args[\"importedGPX\"] = None  # Do not use any GPX path files\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Select your print area\n",
    "- When using an online DEM, there are several ways to define the area you want to print. Use only one and skip the cells for the other two options. Then go to _Setting the tile width_\n",
    "- A)  Enter corner coordinates of a box into a code cell\n",
    "- B)  Use your mouse to digitize a box, circle or polygon on a geemap\n",
    "- C)  Load a kml file (typically created via Google Earth) that contains a single polygon\n",
    "\n",
    "\n",
    "### A) Select print area via lat/long coordinates of its corners (optional)\n",
    "- If you'd rather define your area through actual coordinates, change the default values in the cell below accordingly. \n",
    "- Note that you *must* give it the lat/long of the bottom left (South-West) corner and lat/long of the top right (North-East) corner!\n",
    "- After you've run the cell, skip B and C and jump straight to `Setting the tile width`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Bottom left corner\n",
    "args[\"bllat\"] = 39.322\n",
    "args[\"bllon\"] = -120.374\n",
    "\n",
    "# Top right corner coordinates\n",
    "args[\"trlat\"] = 39.457\n",
    "args[\"trlon\"] = -120.2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### B) Select print area interactively via geemap\n",
    "- If you didn't use a local geotiff or set your the print area's corner coordinates, run the next cell to show an interactive map, from which you will select your print area. \n",
    "- Valid areas are covered by a grey hillshade layer in the background. If your desired area is not covered, go back and select the worldwide DEM source, and re-run the next cell.\n",
    "- If you're importing GPX files, they will show up on the map as cyan lines.\n",
    "- To find the desired print area, use left mouse drag to pan and mouse wheel (or +- buttons) to zoom in/out.\n",
    "- You can also use the search buttons (globe on top left or spyglass) which will place a marker at the result's location."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create an interactive map and center on default area\n",
    "center_lat = (args[\"trlat\"] + args[\"bllat\"]) / 2\n",
    "center_lon = (args[\"trlon\"] + args[\"bllon\"]) / 2\n",
    "Map = geemap.Map(center=(center_lat, center_lon), zoom=7) \n",
    "\n",
    "# make a hillshade layer and add it to map\n",
    "dem = ee.Image(args[\"DEM_name\"]) # DEM source\n",
    "hs = ee.Terrain.hillshade(dem, 315, 35) # sun azimuth and angle \n",
    "vis_params = {'min': 0,'max': 255,} # greyscale color ramp\n",
    "Map.addLayer(hs, vis_params, 'hillshade', shown=True, opacity=0.5) # semi transparent overlay\n",
    "\n",
    "# if GPX files were used, add them to the map\n",
    "if args[\"importedGPX\"] != None and len(args[\"importedGPX\"]) > 0: \n",
    "        gpx = ee.Feature(convert_to_GeoJSON(args[\"importedGPX\"]))\n",
    "        Map.addLayer(gpx, {\"color\":'00FFFF', \"strokeWidth\":\"1\"}, \"GPX line\", opacity=0.9)\n",
    "\n",
    "Map # makes the interactive map show up as output of this cell"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "- Once you found a good general area, hit a Draw button in the center left to digitize the exact outline of your terrain model. \n",
    "- Your options are: Draw a Polygon or Draw a Rectangle or Draw a Circle. __Do NOT use Draw a Marker or Draw a Polyline!__\n",
    "- Draw a Rectangle is the simplest method.\n",
    "- Note: I do not know how to edit or delete outlines. If you change your mind you can simply draw another outline on top of previous outline, which will then be used, even as the old outline is still visible. If this gets too cluttered, you can always re-run the cell above and start over with a clear slate.\n",
    "- Once you're happy with your outline, run the cell below. It will store the (last) outline and use it to create your terrain model. If you change your mind, simply draw another outline and re-run the cell below, it will always take the most recent outline.\n",
    "- After running the cell below, skip C"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# make and store a GeoJSON polygon from (last) digitized outline\n",
    "polyft = Map.draw_last_feature # get last outline\n",
    "args[\"polygon\"] = Polygon(polyft.getInfo()['geometry']['coordinates'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### C) Using a KML file to define the outline of the area\n",
    "- Instead of digitizing an outline in the geemap, you could instead use a polygon stored in a kml file. You can digitize a polygon in Google Earth and store it as a kml file (NOT a kmz file!). \n",
    "- In Jupyterlab click on File Browser on the right and drag your kml file into the panel to upload it\n",
    "- Check that the kml file in the same folder as the notebook and set `poly_file` to its location.\n",
    "- The *stuff* folder contains an example kml file"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Comment out either this line:\n",
    "args[\"poly_file\"] = None # Don't use a kml file\n",
    "\n",
    "# or both of these lines:\n",
    "#args[\"poly_file\"] = \"stuff/polygon_example.kml\" # location of kml file to use\n",
    "#args[\"polygon\"] = None  # ensures that any gee polygon you might have digitized is not used"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Setting the tile width\n",
    "- (If you used a local geotiff file as DEM, resume here)\n",
    "- The tilewidth setting defines how (physically) large the selected print area will be after it's been printed. Units are in mm.\n",
    "- By width, we mean the extent of you model in the East-West direction. The height will be automatically calculated based on the area you selected earlier\n",
    "- Change the value in the cell below to your liking and hit Shift-Enter"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "args[\"tilewidth\"] = 120 # in mm"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Setting the number of tiles and their and setup  \n",
    "- It's possible to divide the print are into multiple tiles. This will results in several STK files instead of just one.\n",
    "- This is useful if you want to print several (smaller) tiles that each fit on you buildplate and later glue them together into one large model.\n",
    "- If you just want a single STL file, set both, ntilesx and ntilesy, to 1\n",
    "- For multiple tiles, decide how many tiles you want along East-West (ntilesx) and how many along North-South (ntilesy)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "args[\"ntilesx\"] = 1 # number of tiles in x  \n",
    "args[\"ntilesy\"] = 1 # number of tiles in y    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Setting the Base thickness (in mm)\n",
    "- The basethick setting determines how much material is put beneath the thinnest part to the terrain print \n",
    "- Use a value of at least 0.5 mm, more if you want a beefier base"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "args[\"basethick\"] = 0.6 # in mm"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Setting the print resolution\n",
    "- Set this value to the diameter of you nozzle size or slightly below. \n",
    "- Tinker with this only if you know what you're doing. This setting defines how much of the fine details the STL file will contain. The detail you're realistically able to print is limited by your nozzle size. If you set setting much lower than your nozzle size, the STL file will be needlessly large, the slicer will take longer but your print will come out the same as if you had used approximately your nozzle size.\n",
    "- In almost all cases, 0.4 mm will be fine for 3D printers.\n",
    "- If you are using a local geofiff file, setting this to -1 will use the native resolution of the geotiff. This is typically overkill b/c of the nozzle limitation and may lead to huge models that may be too much for you system to handle!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "args[\"printres\"] = 0.4 # in mm"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Setting the z-scale (elevation exaggeration factor)\n",
    "- To print the terrain in its \"true\" form (without any vertical scaling applied), set zscale to 1.0. This works well for terrain with great elevation differences, such as the Grand Canyon or Mt. Fuji\n",
    "- Most other terrain usual benefits from a z-scale larger than 1. For gentle hills, use 1.5 to 2.5. For cities use 2.5 to 6. For river deltas and other low relief areas use up to 10.\n",
    "- The height of your printed terrain should be at least 20 - 30 mm high to show good detail. You can check the processing log for `top min/max`, max should be least 20 - 30 mm. If this is too low, use a higher zscale and process again.\n",
    "- Alternatively, you can set this to a __negative number__ which will be interpreted as the desired height of the tallest terrain point in mm. Examples:  -12.7 means \"make 1/2 inch tall\", -20 means \"make 20 mm tall\", etc."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "args[\"zscale\"] = 1.5 # elevation scale factor"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Set the name of your terrain model zipfile\n",
    "- Once a STL file of your terrain model has been created, it will be zipped into a zipfile and copied into the tmp folder. The zipfile also contains a log file and a geotiff.\n",
    "- It's often a good idea to give the zipfile a name that reflects the terrain, e.g. grand_canyon.zipfile\n",
    "- Set zip_file_name to the name of your zipfile. Dot not add the .zip extension, this will be done automatically\n",
    "- With Jupyterlab, right click on the zip file and choose Download from the pulldown"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "args[\"zip_file_name\"] = \"myterrain\" # terrain model will be inside tmp/myterrain.zip"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Other settings\n",
    "- There are several more expert settings which we will skip for now.\n",
    "- If you're interested, look here: https://github.com/ChHarding/TouchTerrain_for_CAGEO#processing-parameters\n",
    "- If you're interested, run the cell below to list all setting names and their values\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "for name in args:\n",
    "    print(name, args[name])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Generating the STL model file\n",
    "- Running the next cell will convert the DEM (either from a local geotiff file or from a Google Earth online DEM source) into STL file and put it inside a zipfile in the tmp folder. You will also get a log file and the geotiff that was processed.\n",
    "- This may take some time!\n",
    "- During processing you'll see a star indicator (In[*]) and a lot of log messages. Those messages will also be in the logfile inside the zip, and may be useful later."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# create zipfile under tmp with the STL file of the terrain model\n",
    "totalsize, full_zip_file_name = TouchTerrain.get_zipped_tiles(**args) \n",
    "print(\"Created zip file\", full_zip_file_name,  \"%.2f\" % totalsize, \"Mb\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Preview the model\n",
    "- run the cell below to get a 3D Preview of the model. If you have multiple tiles they will have different colors."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# unzip zif file into a folder a\n",
    "folder, file = os.path.splitext(full_zip_file_name) \n",
    "zip_ref = zipfile.ZipFile(full_zip_file_name, 'r')\n",
    "zip_ref.extractall(folder)\n",
    "zip_ref.close()\n",
    "\n",
    "# get all stl files (tiles) in that folder\n",
    "mesh_files = glob(folder + os.sep + \"*.STL\")\n",
    "\n",
    "# Create 3D plot\n",
    "plot = k3d.plot()\n",
    "\n",
    "# Add all tiles with a random color\n",
    "for m in mesh_files:\n",
    "    col = (randint(0,255) << 16) + (randint(0,255) << 8) + randint(0,255) # random rgb color as hex\n",
    "    buf = open(m, 'rb').read()\n",
    "    plot += k3d.stl(buf, color=col)\n",
    "plot.display()\n",
    "\n",
    "# remove folder\n",
    "rmtree(folder)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Final thoughts\n",
    "- You can now download your zipfile from the tmp folder and unzip it to 3D print the STL file.\n",
    "- It will also contain a log file and the geotiff it used to create the STL.\n",
    "- Click on the *File Browser* icon on the very left to your notebook and then double-click on _tmp_\n",
    "- Right-click on the zip-file and go to Download\n",
    "\n",
    "## Long-term binder use\n",
    "- I'm unclear on how long a binder instance exists when it's not being used. \n",
    "- It's quite possible that the binder binder instance won't \"stay open\" for longer than a couple of hours(???)\n",
    "- This is not really an issue, it just means you'll have to start a new binder when you return to the browser after a while: https://mybinder.org/v2/gh/ChHarding/TouchTerrain_for_CAGEO/HEAD?labpath=TouchTerrain_jupyter_starters_binder.ipynb \n",
    "- Note that you will need to wait for the installation again and re-do your Earth Engine authentication.\n",
    "- Also, the new instance will not preserve any zip files that you might have created in the old instance (or any file you uploaded), so make sure to download these right away!\n",
    "- If you want to make sure that the kernel stays busy and so your instance doesn't die, you can run the cell below. It will do nothing (endless loop with a 1 second pause) but keep the kernel busy. Once you want to use other cells again you will need to interrupts the kernel first: Kernel - interrupt (ignore the error). ALso I don't know how long this will work and you should not abuse it!\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# endless loop\n",
    "import time\n",
    "while True: \n",
    "    time.sleep(1)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.10.6 64-bit",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.6"
  },
  "varInspector": {
   "cols": {
    "lenName": 16,
    "lenType": 16,
    "lenVar": 40
   },
   "kernels_config": {
    "python": {
     "delete_cmd_postfix": "",
     "delete_cmd_prefix": "del ",
     "library": "var_list.py",
     "varRefreshCmd": "print(var_dic_list())"
    },
    "r": {
     "delete_cmd_postfix": ") ",
     "delete_cmd_prefix": "rm(",
     "library": "var_list.r",
     "varRefreshCmd": "cat(var_dic_list()) "
    }
   },
   "types_to_exclude": [
    "module",
    "function",
    "builtin_function_or_method",
    "instance",
    "_Feature"
   ],
   "window_display": false
  },
  "vscode": {
   "interpreter": {
    "hash": "b1be0222797457612977eb3eaa00946922d56583fa52c09202534133b3ce7849"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}