Make a 3D map from satellite images

Make a 3D map from satellite images#

In about 10 minutes, in your browser, with nothing to install. This guide runs the NASA Ames Stereo Pipeline (ASP) on real satellite images and shows you the result: a 3D model of the terrain (a DEM) and a PDF report.

1. Sign in to GitHub#

You need a free GitHub account. If you don’t have one, create one, then sign in.

2. Click the button#

Open in GitHub Codespaces

A GitHub page opens with a green Create new codespace button. Click it.

GitHub's "Create a new codespace" page, with the green button labeled

Used this before? Then the page says “Resume codespace” instead, with your previous workspace listed. (1) Create a new one starts fresh: an options page follows; leave its settings as they are and click Create codespace. (2) Resume this codespace picks up where you left off, with your files; Tutorial 1 won’t start again by itself there, so click Run All (shown below).

GitHub's "Resume codespace" page, with its two buttons labeled

The options page after "Create a new one", with the "Create codespace" button boxed

GitHub then builds a workspace for you with everything installed: a page says “Setting up your codespace”, and then VS Code appears in your browser with a message at the bottom right while it connects. Nothing asks you to do anything for between 30 seconds and a minute.

GitHub's "Setting up your codespace" page, then VS Code connecting

3. Click “Trust Folder & Continue”#

A box asks “Do you trust the authors of the files in this folder?”. Every new workspace asks this once. Click Trust Folder & Continue.

The trust dialog, with the "Trust Folder & Continue" button

4. Watch Tutorial 1 run#

Tutorial 1 opens within a few seconds and, between 30 seconds and a minute later, starts running by itself. You don’t have to click anything.

Tutorial 1 just after it opens, with the parts of the window labeled

  1. The file explorer: notebooks/ holds the three tutorials, and data/ fills with the images and results.

  2. The tutorial itself: each step has a short explanation and how long it takes.

  3. The step that is running: its code (shown as one line; click it to see it all), the command, the last lines of its output and the time so far. When it finishes, its figures appear with a caption. Scroll down to follow it.

What to expect:

  • About 10 minutes in all, sometimes 15. The longest step, matching the two images, takes most of it and fills in a map of the mountain as it goes.

  • A pop-up may say “High codespace CPU (100%) utilization detected” while the images are matched. That’s expected (stereo uses every core); close it.

  • When it’s done, the end of the notebook shows figures from the report and a large link to open the PDF; a notification at the bottom right says the results zip is ready, and the zip appears at the top of the file explorer.

The end of Tutorial 1: the report link, the results line and the zip in the explorer

  1. The link that opens the PDF report.

  2. The last step’s result line: the zip’s name and size.

  3. The zip itself, at the top of the file explorer: right-click it and choose Download.

The first time you right-click in the explorer, your browser may ask whether the page can see your clipboard. Click Allow or Block, whichever you prefer; the menu with Download appears either way.

The browser's clipboard question, with Block and Allow buttons

If nothing has started after a couple of minutes, or to run it again later, click Run All in the toolbar at the top of the notebook:

The top of the window: the notebook's toolbar, with the Run All button boxed

5. Then#

  • Tutorials 2 and 3 use sharper WorldView-3 images of a hill in San Diego. They don’t start by themselves: open one from the explorer and click Run All, the button shown above. About the tutorials.

  • What just happened? What ASP is and the pipeline, step by step.

  • Your results: the last step of each tutorial puts them in one zip file to download and open in QGIS or ArcGIS.

  • Your workspace stays as you left it. GitHub stops it after half an hour of inactivity and deletes it after 30 days; the free monthly hours and other details are on the Codespaces page.

More#

This guide covers one straightforward path through ASP, which has hundreds of options for dozens of sensors; the official ASP documentation is the reference.

Reporting problems#

For anything broken, wrong or unclear, open a problem report; the form asks for the few details needed to follow up. Questions about ASP itself belong on the ASP support forum.