To sign in to GBDX Notebooks, these are required:
|GBDX credentials||The GBDX credentials you received when you purchased your GBDX subscription are used to log into GBDX Notebooks.|
|A Github Account||We link to your GitHub account so you can publish Gists and share notebooks with groups and organizations that may already exist in your GitHub accounts. You'll only need to link your accounts on your first login.|
To sign in to GBDX Notebooks with your account credentials, go to https://notebooks.geobigdata.io . Click the "Log in" button at the top right of the screen. The login box will appear. Enter your credentials to start the process.
Log in with your GBDX User Account credentials.
Next, you'll be prompted to connect your GitHub profile. Enter your GitHub credentials to connect your account. If you don't have one, you can create one from this menu.
Connect your GitHub profile to GBDX Notebooks, or create a GitHub profile if you don't have one.
Once you click "connect", your GBDX and GitHub accounts will be connected.
GBDX Notebooks is organized into five top level sections. Use the top navigation menu to visit each section.
GBDX Notebooks top navigation menu
|My Library||Select "My Library" to see the library of notebooks you've created.|
|Discover||Explore published notebooks, and clone and edit publicly available Notebooks you want to try.|
|+New Notebook||Create a new notebook using the "New Notebook" tutorial, or start from a blank notebook.|
|Documentation||Read the GBDX Notebooks user documentation.|
"My Library" displays the Notebooks you've created. From this page, edit, duplicate, or delete a Notebook.
Filter your view by selecting one of the links to the right of the word "Notebooks".
|All||Choose "All" to see your drafts and published notebooks|
|Drafts||Choose "Drafts" to see only your notebooks that have not been published yet.|
|Published||Choose "Published" to see only notebooks that you have published.|
"My Library" page, with the "All" view selected. This view shows all drafts and published Notebooks.
The "My Library" page displays a "cover" view of each of your notebooks. Each cover provides basic information about the Notebook, and allows the user to take a series of actions.
|Name||The name given to the Notebook by the author|
|Author||The Username of the Notebook's author|
|Permissions||The permissions levels are "public" and "private". The default is "public"|
|Date and Time||The date and time the Notebook was published|
|Cover Image||Displays the image provided by the Notebook's author|
|Tags||The tags provided by the Notebook's author. These tags are searchable from the "Discover" section. Tags only appear on the cover once the Notebook has been published|
|Description||The short description provided by the Notebook's author|
|Draft||If the notebook has not been published, the cover will show "draft", and the description will be "Not published yet."|
From the Notebook cover, the following actions can be executed:
|Open||Open and edit the content of an existing Notebook.|
|Delete||Delete the Notebook. This will delete the contents and cover.|
|Details||Click "Details" to view the code and output of a Notebook. Metadata can be updated from the details page by clicking the pencil icon next to the name. Notebook content is not editable in this view.|
The "Discover" page lets you browse tutorials, search and explore published Notebooks, and clone and edit a public Notebook.
From the Discover page, you can search for, clone, and edit public Notebooks, View Notebook tutorials, and see newly published Notebooks.
The "Explore Notebooks" search feature lets you search for public Notebooks that meet your needs. When you type a word or phrase into the search box, our search engine looks for a full or partial match in the following fields:
- Author name
Search results are segmented by "Notebooks" and "People". For example, a search on the term "coast" returns a series of Notebook tutorials with the term "coast" or "coastal" in the title. It also returns a series of Notebooks published by Steve Coast.
Notebooks search results: Notebooks with the phrase "Coast" in the title
People search results: People with "Coast" in their name who have published public notebooks
The "Notebook Tutorials" section displays collections of tutorials. A collection is a group of tutorials that fall into the same category. Select the collection to view the Notebooks within it.
Notebook tutorials are organized into "collections".
These Notebooks tutorials will walk you through the basics on how to access imagery, and perform various operations against that imagery. The Notebooks are a great way for users to interact with the data with Python, and to learn about the structure and capabilities of DigitalGlobe imagery.
For more information on "gbdxtools", a Python=based tools suite for interacting with GBDX, see gbdxtools documentation.
This section displays Notebooks that have been published recently. The newest Notebooks are displayed first.
Once a search is executed, the set of Notebook covers that match the search criteria will be returned. Only publicly available Notebooks are returned.
From this view, the Notebook cover shows the following details:
|Name||The name given to the Notebook by the author|
|Author||The Username of the Notebook's author. Click on the author's name to see other Notebooks they've authored.|
|Permissions||Only Notebooks with permissions set to "public" appear in this view.|
|Date and Time||The date and time the Notebook was published.|
|Cover Image||Displays the image provided by the Notebook's author.|
|Tags||The #tags provided by the Notebook's author. These tags are searchable from the "Discover" section.|
|Description||The short description provided by the Notebook's author.|
From this view, the following actions can be executed:
|Details||Select "Details" to view the code and output of a Notebook. Content is not editable in this view.|
|Clone and Edit||Selecting the "Clone & Edit" button will create a copy of the Notebook in your own Jupyter Notebook environment. From there you can rename the Notebook, interact with the code, add new code, change the Area of Interest, and more. When you're ready, you can publish the Notebook.|
This page lets you create a new Notebook. There are two options available for Notebook creation:
|Start with Imagery||This option opens an introductory tutorial with imagery and code samples. This option is ideal for first-time users.||Recommended|
|Blank||This option opens a new Notebook with no code snippets or imagery. To use this option, you'll find imagery by using the AOI selection tool, and create your Python analysis from scratch.||Advanced|
When a new Notebook is created, it defaults to Python 3. To update to Python 2 for a new Notebook:
- Select "kernel"
- Scroll to the bottom of the kernel menu and select "change kernel."
*Select "Python 2"
Change the Python version for a new Notebook
The Documentation link brings you back to the documentation you're reading now. You can easily access the GBDX Notebooks course from this link, or from the sidebar navigation on GBDX University.
GBDX Notebooks tutorials are available from within the application. For example, to see the tutorial "Introduction to Image Access with GBDXTools", Choose "New Notebooks", and then "Start with Imagery". Other tutorials can be accessed from the "Discover" page.
View the Notebook details page by clicking the Notebook title or the "Details" button from the Notebook cover. Leave a comment for the Notebook author, or reply to a comment.
At the top of the Notebook details page, you can view the following:
- Public or Private
- Cover image
- Published Date
- Searchable tags
There are two ways to comment on a Notebook from the Details Page:
- Select "Comments" from the top of the Details page
Select the "comments" link from the menu
- Scroll to the bottom of the Notebooks Detail Page to see the comments block.
The "Clone & Edit" button is available from the top of the Notebook Details Page. This button lets you clone a public Notebook, and then edit the contents of the copy.
Select "Code" to see the code used to create the Notebook in "read-only" mode. In this view, you'll see the main description, the section descriptions, the input code blocks, and the output of each section.
Select "Outputs" to see only the outputs of the Notebook. In this view, the code blocks are not displayed.
To create a new Notebook, select "+New Notebook" from the top navigation bar. You can select one of the following ways to start your new Notebook:
Start with Imagery: This option opens an editable tutorial in your Juypter Notebooks environment. The tutorial walks you through selecting imagery and adding code to your Notebook. For first time users, we recommend this option.
Blank: This option opens a blank Notebook with no tutorials. You'll use the "imagery" tool on the left sidebar to select imagery.
Once you start to create a new Notebook, you'll notice some differences between your GBDX Notebook and a standard Jupyter Notebook. While the default Notebook behavior is as standardized as possible, we've made changes to streamline your access to DigitalGlobe's imagery catalog.
The custom GBDX Notebooks toolbar will be displayed on the left side of the page. The toolbar offers the following options:
GBDX Notebooks custom toolbar
|Tool or Link||Description|
|Imagery||The "imagery" icon opens the Area of Interest selection tool. Use this tool to search for imagery and create and save an Area of Interest.|
|Deploy||Notebooks can be deployed as "tasks". The "Deploy" icon opens a form page where you'll input your task information and add your input and output requirements. From here, select "Publish" to deploy the task.|
|Orders||The "Orders" icon shows the status of imagery orders. Once an order is complete, you have the option to "insert" the image right from the status box.|
Select the "Imagery" icon from the sidebar to open the AOI selection tool.
GBDX Notebooks are designed to give access to small AOIs for users to build their methods and algorithms against. The AOI selection tool is zoom-level dependent. The red bar at the bottom of the map lets you know the AOI you've selected is too large. Keep zooming in until the bar turns green. Once the bar turns green, the text will say "Draw a rectangle to select an area of interest."
To start a search, we recommend typing a location in the search box. It can be a general area, such as "Denver" or a more specific area such as Denver International Airport, Denver, CO. Be as specific as possible to narrow your search.
To zoom in or out to change your AOI, you can:
- Use the +(plus) button to zoom in, or the -(minus) button to zoom out.
- Double click the left mouse button to zoom in.
- Scroll your mouse wheel down to zoom in, and up to zoom out.
In this example, the AOI is too large to allow imagery selection. The user will need to continue to zoom in to a smaller area. When the area is small enough, the zoom bar will turn green.
Once you have zoomed in to a small enough area, draw a polygon around the specific area to create an AOI. There are two ways to draw a polygon:
Select the polygon icon, then click the starting location for your area. Draw and connect each side of your polygon.
Select the square icon. Click the start location for the square, then drag to create the boundaries.
Once an area has been selected, the bounding box is shown in the green bar.
Once you select an AOI, the search button at the bottom of the screen will be enabled. Select this button to execute a search. You can set search filters to narrow your results.
To set search filters before executing a search, click "Search Filters" in the lower left corner of the pane.
When a search is executed, the search results pane is displayed. A horizontal scrolling selector is displayed for each filter. Once the filters are set, select the "search" button to execute the search.
Drag the control to the left or the right to change the filter values.
When a search is executed, the image count is displayed at the top of the screen, and the results display at the bottom of the pane.
There are 46 images in this results set.
To narrow the results set further, choose "Additional Filters" in the top left corner of the pane. This brings up the filter box, and the filters can be changed using the horizontal scroll bar.
GBDX Notebooks have access to imagery from the following sensor platforms:
The Search Results view displays the following for each record:
|Checkbox||Click to check the box next to a record. Clicking the box activates the "insert code" button in the lower right corner.|
|Date||The date the image was acquired by the satellite.|
|Coverage||Each record is part of the specific AOI you defined; not part of a full image strip. Coverage shows how much overlap exists between your AOI and the strip. 100% means that the image covers the entire AOI you selected.|
|Source||The source is the satellite that acquired the image.|
|Clouds||The percentage of cloud cover in the image. This will help you determine if the image will be useful or not.|
|Preview||Preview lets you view the image before adding it to your Notebook.|
|Insert||Selecting "Insert" adds the image request code to your Notebook, and fetches the image for preview.|
|Order||Some images are not available for immediate use, and need to be ordered. Click "Order" to begin the process. See Order an image for more information.|
Selecting "Preview" displays the image and its metadata. If you need to find the catalog ID for an image, it's listed in this view.
The preview pane shows the select image and its associated metadata.
To add an image to a Notebook, the image must be available. Some images are not immediately available and need to be ordered from the DG factory.
If an image is available for immediate use, the link at the end of the row will say "insert."
If an image is not available for immediate use, it will to be ordered. The link at the end of the row will say "Order."
Your account will be charged when you order an image. Once an order is placed, it cannot be canceled.
This search results set includes images that are available to insert into a Notebook, and an image that needs to be ordered. Clicking "Order" will start the order fulfillment process.
When you click "order" from the search result, a pop up message will warn you that:
- Your account will be charged for the ordered image
- The order cannot be canceled once the user hits "continue"
- Order fulfillment can take several hours
To complete the order, hit "continue."
Order fulfillment can take several hours. To check the status of an order, click "Orders" in the custom toolbar. The list will show pending and completed orders.
Clicking "Orders" brings up a list of ordered images and their status.
|Order submitted||The order has been been placed, but fulfillment hasn't started yet.|
|Order processing||The image order has been placed to the factory, but has not been delivered yet.|
|Order complete||The ordered image has been delivered, and is now available to insert into a Notebook.|
When an Order is "complete", you have the option to insert it into your Notebook from the order status box. In the search results list, the link that said "order" will now say "insert."
Selecting the "trash" icon removes the line item from the order status box. It does not cancel the order or delete the image.
Once you find an image you want to add to your Notebook for processing, click "insert" from the individual record in the search results, or in the preview pane. This will insert the cell for importing the image into the Notebook, and fetch the image. The cell gives key information about the image, and lets you begin analyzing the imagery. From this cell, you can find the catalog ID and bounding box. It has also plotted the multispectral band for the image.
Many published and publicly available Notebooks have a cell like this as the first cell in the Notebook. You can insert your own cell into the Notebook. This will allow the Notebook to work on the AOI you've selected instead of the AOI included by the original author.
To insert multiple images at once, click the check box next to each image you want to insert. This will activate the "Insert Code for [number] Images" button.
When you insert code for multiple images at once, the result is a code snippet containing a JSON file. The JSON file contains pointers to all the images you selected.
Using multiple images can be necessary when working with time series, working with change detection, creating mosaics, or anything else you can come up with. For more details on using the notebooks, and interacting with DigitalGlobe imagery you can access our Notebook tutorials, which will walk you through other common operations such as working with the various imagery bands, reprojecting the images, and viewing the full metadata.
The GBDX Notebooks Tutorials are the best way to learn how to add capabilities to your Notebook with Python.
This is an example of a GBDX Notebooks tutorial.
Tutorial Notebooks can be cloned, and then edited for your own use.
Once you've created a Notebook that performs as you expect it to over a small AOI, you can scale your Notebook over much larger areas by deploying it as a GBDX task. This is a quick and easy way to deploy a task on the GBDX platform, without having to deploy it in a Docker container. This removes much of the overhead work of task deployment.
To deploy a task, click the "Deploy" icon from the toolbar. This will open a new pane. In this pane, you'll add input variables, output variables, and task information.
In the example below, this Notebook requires two catalog IDs, a "before" image and an "after" image, as well as a bounding box. These fields are populated into the ‘Deploy’ tab by looking for variables within the Python code you’ve written in your Notebook. You must have successfully executed a cell using that variable in order for it to show up as an option for the input. You can then use the drop downs under ‘Type’ to specify what type of variable this is.
Outputs work in the same way. Variables that were specified within the Notebook will appear here. In this example we have a variable called ‘total_feaures’ which will output a string with the number of tents that were detected within the bounding box, as well as an output file, which will be output as a GeoJSON file.
After you've specified your required inputs and outputs, you can give your task a name, description, and version number. Once you’ve deployed this task it will be available to run in your Notebook, or directly from "gbdxttools".
Once all the information has been populated, click the "publish" button to deploy your task.
Once you have "published" or "deployed" a task, it will appear in the "Deployed Tasks" List. The task will first appear in "pending" state. This means it's in the process of being published. Once deployment is complete, a "run" button will appear next to the task.
Select "Deployed Tasks to see a list of tasks published by you. The task in this example has just been deployed, and is still in the "pending" state.
This example shows the same task once deployment is complete. The "run" button is now available, which allows you to run the task.
|Pending||The task deployment is running, but is not complete. Deployment can take up to 10 minutes.|
|Run||Task deployment is complete. The task is now available to "run".|
From the "Deployed Tasks" list, the following is displayed for each task:
- Task Name
- Notebook Name
- "Move to Trash" icon
Once you click the "Run" button next to a task, you'll be able to run your task on GBDX at scale.
To run a task from the "Deployed Tasks" list:
- Select the "Run" button to the right of the task
- Add the required inputs. These are the inputs you defined when deploying the task.
- Click the "Run Task" button
In this example, this task requires 2 catalog IDs and a bounding box. Input this information in the correct boxes, and then select "Run Task".
Selecting "Run Task" adds your task to the GBDX queue. When a task is submitted to the queue, a "Task Run History" line item is displayed for the task. The "Task Run History" shows:
- Date and Time submitted
- A "Logs" button
- An "Output" button (this button is grayed out until the task is complete).
This example shows the "Task Run History" for the deployed task.
The "logs" section lets you check the status of your task,. From this view, you can see the tasks' events and states, along with any errors encountered during the task run.
Once the task has finished running, the "Output" button will become active. Selecting this button will show you the outputs you specified when deploying the task.
This example shows the output of the Tent Counting algorith. The outputs are a feature count of 6,837 tents and a viewable GeoJSON file. You can now continue working with the GeoJSON in the Notebook, or view the results on a slippy map.
Using the ‘Deployed Tasks" tab is the fastest and easiest way to scale up an arbitrary analysis you’ve created in your Notebook. Once you’ve created the task, it's simple to run it on other areas. You can run the same task with new Catalog IDs and a new bounding box. You can also specify multiple Catalog IDs to deploy your tasks at massive scales.
Publishing your Notebook allows you to share it with the community or with other users privately. Once a Notebook is published, it appears in the list on the "Discover" page.
Once your Notebook is ready to be shared, click the "Publish Notebook" button.
Click "Publish Notebook" to make your Notebook available for sharing.
When a Notebook is published, it can be set to "private" or "public". "Public" Notebooks are viewable to all users from the "Discover" page. "Private" Notebooks can be set to be available only to you, or to a GitHub organization or group.
Permissions can only be set on Notebooks that have been published. The default permissions setting is "Public".
To change the permissions settings for a Notebook, do the following:
- From "My "Library", find the Notebook you want to update
- Click the "Details" button on the Notebook cover (if the task has not been published yet, the "details" button will not appear).
- From the "details" page, click the pencil icon next to the name. This will bring up a dialog box.
Click the pencil icon next to the name to update Notebook metadata and change the privacy settings.
- From this dialog box, you can update the Notebook's metadata, "unpublish" the Notebook, or change Permissions. Select "Permissions" to change the setting.
Select "Permissions" to change the setting from public to private, and to share the Notebook with a group or organization.
From the "Global Permissions" page, select "Public" or "Private". If you select "Private", additional "Private" settings will be enabled.
To keep the Notebook private to you only, no other selections need to be made.
To keep the Notebook private, but share with your GitHub organization or group, choose the edit buttons and make a selection from the available options.
- Once you've added or updated the metadata and privacy settings, select "publish" in the bottom right corner.
Click "publish" to publish the metadata that accompanies your Notebook.
You can cancel publishing by clicking the "Cancel Publishing" button on page shown above. This button only appears when the Notebook has already been published.
Our hosted Notebooks have integrated access to publishing your Notebook as a gist. Click on the small arrow next to the ‘CellToolbar’ to automatically publish the Notebook you’re currently working in as a Gist, which can be accessed through your GitHub account.
To learn more about Jupyter Notebooks, see Jupyter Documentation
To report an issue or give feedback on GBDX Notebooks, click the "feedback" link on the right side of the window and fill out the feedback form.