Portable Globe and Server 5.2¶

• Overview
• Installation
  • Globe cutter installation
  • Portable globe server installation
• Creating a portable globe
  • Before you begin
  • The globe cutter interface
  • Globe name
  • Drawing the polygon
  • Globe resolution
  • Building the globe
• Portable server
  • Serving a globe
  • Broadcasting a globe
  • Changing the globe being served
• Connecting to a portable globe
  • Google Earth EC
  • Google Earth API
  • Defining options in portable.cfg
• Command line reference
  • gepolygontoqtnodes
  • gerewritedbroot
  • gekmlgrabber
  • geportableglobebuilder
  • geportableglobepacker

Overview

The Google Earth Enterprise Portable Server solution enables organizations to access portions of their custom globes in the field when no network access may be available or possible. Using a web interface, end users may select an area of interest to download from a Google Earth Enterprise Server for offline use on their Linux or Windows laptop with the Portable Server application.

All data available within a specified area of interest is downloaded and stored in a portable globe, including all high-resolution imagery, terrain, vector data, KML files, and searchable Point of Interest (POI) locations. Outside of the specified area of interest, only low resolution imagery and terrain will be stored in a portable globe. These levels of resolution can be specified when the globe is cut.

Portable globes may be specified, generated, and downloaded in as little as a few minutes — depending on the area of coverage — to support rapid preparation for first responders. Larger globes may be built in advanced preparation for responders to have ready on the shelf.

The Portable Server solution is made up of two applications:

• The globe cutter tool, which is installed on a production Google Earth Enterprise Server system hosting a 3D database. This tool allows end-users and administrators to select, package, and download a portion of the 3D Earth as a portable globe file.
• The portable server is installed on Linux or Windows machines in the field. It can operate in a single-user mode for complete offline usage by one user, or can broadcast a portable globe so that multiple Portable Server users, and/or mobile users with compatible Android-based smart phones, can view the same globe.

Installation

This section describes installation of the two applications that make up the Portable Server solution.

Globe cutter installation

The portable globe cutter tool is installed with Google Earth Enterprise Server Open Source. Globe cutting is disabled by default; to enable it you must set the --enable_cutter flag for geserveradmin from the command line:

# geserveradmin --enable_cutter

By default, the cut globes will be stored in the /opt/google/gehttpd/htdocs/cutter/globes directory. The cut globes can be large, and many servers do not have sufficient storage allocated in this directory for multiple globes. If this is the case for your server, you may consider designating a different directory as the storage area for the cut globes.

Portable globe server installation

The portable server is supported on:

• Linux distributions Cent OS 7, RHEL 7, Ubuntu 14, Ubuntu 16
• Windows 7 and 10

Refer to the Portable Server Wiki page for build and install instructions.

Creating a portable globe

Cutting a globe is accomplished with a simple web interface. You will use your mouse, or import a KML, to define a polygon, which defines your ‘area of interest.’ This polygon not only defines the area that will display high-resolution imagery, but is also used by Fusion to create a localized search database.

Before you begin

Enable the cutter

Before cutting a globe, you must enable the cutter from the command line:

# geserveradmin --enable_cutter

The globe cutter interface

To create a portable globe, point your browser to http://yourserver/cutter, where yourserver is the server on which Earth Enterprise Server is running. The Globe Creator page appears.

Select the globe you wish to cut your portable version from in the drop-down menu.

Globe name

The globe name defines the file name of this globe; it will be created as a .glb file, which is a single-file format for sharing Google Earth Enterprise globes. Spaces, slashes, and double dots (..) will be converted to underscores in the saved globe name.

We recommend using a descriptive name for each globe, so that others will know what geographic area, or what mission, the globe was created for.

Drawing the polygon

Once the globe name has been specified, you can define the geographic region to be cut by drawing a polygon on the globe. There are two ways to draw the polygon, one of which has been deprecated.

Defining the polygon with KML

You can use a KML to define the polygon(s). The KML should be complete, and may contain single or multiple <polygon> </polygon> elements. To insert your KML:

1. Select the Enter polygon as KML checkbox.
2. Paste your KML into the text field.
3. Click outside of the text field. Your polygon appears on the map, if you are running the deprecated Google Earth plug-in.

Hand drawing the polygon

This method is only available if you are have the deprecated Google Earth plug-in running in your browser.

First, using the navigation controls in the plugin, zoom in to the region of interest. To use your mouse to define the polygon, click the polygon icon in the globe window.

Then, click the globe to define each point. You can use the navigation controls on the right to move the globe or change zoom levels while drawing.

Double-click the final point to complete the polygon selection, at which point the polygon will change from blue to purple.

You can view the KML of the shape you have drawn by selecting the Enter polygon as KML checkbox.

Globe resolution

The polygon you specified in the previous step defines your ‘area of interest.’ This area will contain high-resolution imagery and data, and search tabs will be created for information that lies within this zone. The maximum and minimum resolutions are specified as integers between 1 and 24. These correspond to the zoom levels that are used in the Fusion server.

Minimum resolution

The zoom level for the polygon area is specified in the Maximum resolution to extract field.

A minimum zoom level of 5-7 will present a decent-looking world to the user and will most likely include vector layers such as international boundaries and state boundaries and main cities without affecting the size of the .glb file very much. For example:

• A cut globe with minimum and maximum resolution values set to 5 is 10 MB.
• A cut globe with minimum and maximum resolution values set to 6 is 41 MB.
• A cut globe with minimum and maximum resolution values set to 7 is 120 MB.

These numbers are small in comparison to the overall size of your globe when a suitable maximum resolution has been selected. For example, a globe that contains all of the city of Atlanta, GA, USA in 1-foot resolution requires approximately 5 GB of storage. Even level 7 imagery, at 120 MB, is a small percentage of the overall globe size.

Maximum resolution

The area outside of the defined polygon will be included in the globe at a lower resolution, which is defined within the Minimum resolution to extract field. Areas near the polygon may be included at a higher resolution.

The maximum resolution of the cut globe will be no higher than the maximum resolution of the source globe. For example, if the maximum resolution in the cutter is specified at 24, but the source imagery is at 18 (approximately 1-meter resolution), the cut globe will contain level 18 imagery. You can leave this field blank to use the highest available imagery.

You may enter a lower number to reduce the size of your globe, by not including the highest resolution imagery.

Building the globe

Click Build to start the build process. Depending on the size of your polygon, this can take from a few minutes to a few hours; likewise, file size will vary widely depending on the area selected and the desired resolution.

When the build is finished, a .glb file is created and a download link appears to the file’s location on the Earth Server. Save the file into the <portable-server-unpack-directory>/data directory with the other .glb files. Alternately, the globe file can be copied onto portable media like a DVD, thumb drive, or external hard drive to be delivered to users.

The .glb file contains all that you need to share your portable globe — imagery, terrain, and vector assets, plus the search database. For this reason, it is important to retain control of your globe if it contains sensitive or proprietary information.

Search tabs

When a globe is cut, the search tabs associated with the globe are also bundled with the globe. However, because search plugins in Google Earth Enterprise run within the Tomcat / Apache instance on the Earth server, most search tabs will not work in a portable globe.

The Portable Server uses its own search framework that allows Python code stored on the portable machine to execute in place of the GEE plugin.

KML files

When a portable globe is cut from a source containing KML links in the Layer panel:

• KML files that are stored locally on the primary Earth Server will be bundled into the portable globe. Only the main KML file will be copied, not any links or files that are embedded as links in the main KML file. The default copy is not recursive.
• KML links that refer to servers other than the primary Earth Server are not copied. The layer will be visible in the client, but clicking the link will not cause any data to be displayed. If access to external servers is needed, a small KML file should be stored locally on the primary Earth Server. This KML file should contain a link to the intended external server.

These behaviors can be modified if the globe is built from the command line rather than from the GUI as described in the Command line reference section.

Historic Imagery

Historic Imagery is not supported in the portable globe as of Fusion 4.2.

There are, however, two situations in which historic imagery will be displayed:

• When the computer running the portable globe has a connection to the Earth server from which the globe was cut. In this case, historic imagery can be streamed from the Earth server. Once in the field, however, and disconnected from the Earth server, no historic imagery will be displayed.
• If historic imagery has been cached on the portable globe machine.

Otherwise, the following error message will appear:

Note

Google Earth cannot contact the imagery server to download new images.

You will be able to see areas that you have been to recently, but new image areas may appear blurry.

Portable server

The portable server is a lightweight web server that runs on Linux and Windows computers. The web server starts within seconds and begins serving one of the globes that has been saved to the data directory. Once the globe is served, it can be opened in a web browser.

Serving a globe

Copy the globe to be served into the data subdirectory (or whichever directory is specified as the globes_directory in portable.cfg).

1. To start serving run the following command in the directory where you unpacked Portable Server:

   python portable_server.py

2. Navigate to the Portable Server administrative page at http://localhost:9335. If you have set a custom port number in portable.cfg, substitute that for “9335”.

You can select what globe is being served from the administrative page. Click the folder icon and you will see a screen where you can select what globe or map should be served by Portable Server.

You can shut down Portable Server from the administrative page, as well. Click the menu button, then select Quit.

Broadcasting a globe

To share a globe with others on your network:

1. Make sure disable_broadcasting is set to False in your portable.cfg.
2. If you are not already serving a globe, select the globe to serve from the Portable Server interface.
3. On the Portable Server administrative page, click the Broadcast icon.

Changing the globe being served

To change the globe being served:

1. Point your browser to http://localhost:9335.
2. Click the Folder button.
3. Select the new globe.

If you are accessing the globe with the Google Earth Enterprise Client, log out of the client and log back in to http://localhost:9335.

Connecting to a portable globe

It is possible to connect to a portable globe from a variety of platforms.

Google Earth EC

Launch the Google Earth EC client. When prompted for a server address, enter http://localhost:9335. If you have changed the default port in portable.cfg, use the new port value instead.

Google Earth API

The Google Earth Enterprise Portable Server comes with a preconfigured HTML page that displays your globe using the Earth API. The page relies on the discontinued Google Earth browser plug-in to render globes, so it does not work in most recent browsers. This page is at http://localhost:9335/earth/earth_local.html.

If you wish to make your own custom Earth API application, make a copy of the included file from which to start.

You can also reach the page listed above by clicking view in browser from the administration page at http://localhost:9335.

Defining options in portable.cfg

The server directory under the Portable Server installation directory contains the main configuration file, portable.cfg. This file defines a number of options, but is primarily used to change the port on which the globe is served, if required.

• port: the port on which to serve the globe. Default is 9335.
• globes_directory: the directory in which to look for globe files.
• globe_name: the default globe to serve when the server is started.
• fill_missing_map_tiles: If set to True, enables pixel-filling from ancestor map tile when there are no more tile descendents.
• max_missing_maps_tile_ancestor: Limit the pixelation to 2^x by 2^x sized pixels.
• local_override: If set to True, Portable Server looks for all files on the server first before seeking them on the globe.

Command line reference

The following command line tools are available for the portable globe and server.

• gepolygontoqtnodes
• gerewritedbroot
• gekmlgrabber
• geportableglobebuilder
• geportableglobepacker

Knowledge of these command line tools is not needed for most users and system administrators. The simple cutter interface that is provided should meet the needs of nearly all users. However, if finer control is needed or if the complete creation of globes needs to be automated, these command line tools are available. The following is the series of events for creating a globe to help give a sense of what these command line tools accomplish and in what order they are run:

Building LevelFive ...

No description given. Added globe directory:
/tmp/globe_builder/LevelFive_4282_1287494655.545115/LevelFive Ok

Saved polygon to
/tmp/globe_builder/LevelFive_4282_1287494655.545115/LevelFive/earth/polygon.kml
Convert polygon to quadtree nodes ...
Executing: /opt/google/bin/gepolygontoqtnodes --qt_nodes_file=/tmp/globe_builder/LevelFive_4282_1287494655.545115/qt_nodes.txt
--kml_polygon_file=/tmp/globe_builder/LevelFive_4282_1287494655.545115/LevelFive/earth/polygon.kml
--max_level=18
0 qtnodes Ok

Rewrite dbroot ...
Executing: /opt/google/bin/gerewritedbroot
--source=http://earth.localdomain/default_ge/
--icon_directory=/tmp/globe_builder/LevelFive_4282_1287494655.545115/LevelFive/icons
--dbroot_file=/tmp/globe_builder/LevelFive_4282_1287494655.545115/dbroot.v5
--search_server=localhost
--search_port=9335
--kml_server=localhost
--kml_port=9335
--kml_map_file=/tmp/globe_builder/LevelFive_4282_1287494655.545115/kml_map.txt
8 icons
Executing: cp
/tmp/globe_builder/LevelFive_4282_1287494655.545115/dbroot.v5
/tmp/globe_builder/LevelFive_4282_1287494655.545115/LevelFive/dbroot/dbroot_localhost_9335
Ok

Grab kml files ...
Executing: /opt/google/bin/gekmlgrabber
--kml_map_file=/tmp/globe_builder/LevelFive_4282_1287494655.545115/kml_map.txt
--output_directory=/tmp/globe_builder/LevelFive_4282_1287494655.545115/LevelFive/kml
--source=http://earth.localdomain/default_ge/
--kml_server=localhost
--kml_port=9335
0 kml files Ok

Build globe ...
Executing: /opt/google/bin/geportableglobebuilder
--source=http://earth.localdomain/default_ge/
--default_level=5
--max_level=5
--hires_qt_nodes_file=/tmp/globe_builder/LevelFive_4282_1287494655.545115/qt_nodes.txt
--metadata_file=/tmp/globe_builder/LevelFive_4282_1287494655.545115/earth/metadata.json
--globe_directory=/tmp/globe_builder/LevelFive_4282_1287494655.545115/LevelFive
--dbroot_file=/tmp/globe_builder/LevelFive_4282_1287494655.545115/dbroot.v5 >
/tmp/globe_builder/LevelFive_4282_1287494655.545115/packet_info.txt & Ok

685 image packets
128 terrain packets
515 vectors packets

Extract search data ...
Getting search poi ids:
http://earth.localdomain/cgi-bin/globe_cutter.py?
cmd=POI_IDS&db=default_ge
Getting search poi data:
http://earth.localdomain/cgi-bin/globe_cutter.py?
cmd=SEARCH_FILE&poi_id=&
polygon=Paste%20in%20KML%20containing%20polygon.%20If%20KML%20contains%20more
%20than%20one%20polygon%2C%20the%20first%20polygon%20will%20be%20used.

Saving search poi data:
/tmp/globe_builder/LevelFive_4282_1287494655.545115/LevelFive/search_db/gepoi_ Ok

Add plugin files ...
Executing: cp -r /opt/google/gehttpd/htdocs/cutter/template/earth/*
/tmp/globe_builder/LevelFive_4282_1287494655.545115/LevelFive/earth Executing: cp -r /opt/google/gehttpd/htdocs/cutter/template/maps/*
/tmp/globe_builder/LevelFive_4282_1287494655.545115/LevelFive/maps Executing: cp -r /opt/google/gehttpd/htdocs/cutter/template/js/*
/tmp/globe_builder/LevelFive_4282_1287494655.545115/LevelFive/js Rewrite JSON from: http://earth.localdomain/default_ge//query?request=Json&var=geeServerDefs Ok

Packaging globe for download ...
Executing: /opt/google/bin/geportableglobepacker
--globe_directory=/tmp/globe_builder/LevelFive_4282_1287494655.545115/LevelFive
--output=/opt/google/gehttpd/htdocs/cutter/globes/LevelFive.glb
Executing: chmod a+r /opt/google/gehttpd/htdocs/cutter/globes/LevelFive.glb
/opt/google/gehttpd/htdocs/cutter/globes/LevelFive.glb 9.62MB Ok
Deleting tmp directory as: /tmp/globe_builder/LevelFive_4282_1287494655.545115 Ok

This section uses the following typographic conventions:

gepolygontoqtnodes

Usage

gepolygontoqtnodes --kml_polygon_file=filename

--qt_nodes_file=filename --max_level=int

Description

Creates a list of the quadtree nodes that encompass a polygon at the given max_level.

Required

gerewritedbroot

Usage

gerewritedbroot --source=server_name --icon_directory=directory --dbroot_file=filename --kml_map_file=filename [--search_service=search_service_url] [--preserve_search_service] [--kml_server=server_name] [--kml_port=num] [--kml_url_path=prefix] [--use_ssl_for_kml=bool] [--preserve_kml_filenames] [--disable_historical]

Description

• Reads dbRoot and rewrites the search tabs so that they point to the given search server, port, and path.
• Optionally creates a directory of all of the icons referred to by the dbroot.
• Optionally updates the host, path, and/or file names in KML Layer URLs in the dbRoot.
• Optionally creates a text file that lists the mapping from original KML Layer URLs to their updated file names.
• Optionally removes the reference to the server for historical imagery data.

Required

Options

gekmlgrabber

gekmlgrabber --kml_map_file=/tmp/kml_map

Usage

gekmlgrabber --kml_map_file=filename --output_directory=path

[--source=server_name] [--kml_server=server_name] [--kml_port=num*] [--kml_url_path=prefix] [--use_ssl_for_kml=bool] [--no_recurse=bool] [--ignore_absolute_urls=bool]

Description

Reads KML references, retrieves them from network, and copies them into local files. If the --no_recurse flag is not set, it does the same for any additional KML files referenced within the given KML files.

Required

Options

geportableglobebuilder

geportableglobebuilder --source=http://myserver --max_level=18 --default_level=8 --hires_qt_nodes_file=qt_nodes.txt --globe_directory /tmp/my_portable_globe

Usage

geportableglobebuilder--source=server_name --globe_directory=path

[--max_level=num] [--default_level=num] [--hires_qt_nodes_file=filename] [--dbroot_file=filename] [--nowrite]

Description

Creates a set of packet bundles and other associated files. These files can be combined into a globe file with geportableglobepacker.

Required

Options

geportableglobepacker

Usage

geportableglobepacker --globe_directory=path --output=filename [--make_copy=bool] [--is_2d=bool]

Description

Packs up all globe files into a single file. If --make_copy is set to true, the globe directory is undisturbed. If not, then the globe directory is rendered unusable, but the command can run considerably faster.

Options