Generic hostable User Interface components powered by entwine and plasio.js, e.g. http://speck.ly
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
resources/public FontAwesome 5 and flex layout instead of floats Aug 9, 2018
scripts Docker build Aug 7, 2018
scss FontAwesome 5 and flex layout instead of floats Aug 9, 2018
src FontAwesome 5 and flex layout instead of floats Aug 9, 2018
support
vendor EPT updates Jun 2, 2018
.gitignore Get initial version of scrub to work Nov 10, 2017
Procfile
README.md Docker build Aug 7, 2018
dev.sh Get initial version of scrub to work Nov 10, 2017
project.clj More bootstrap 4 fixes Aug 6, 2018

README.md

What is plasio-ui?

plasio-ui is a prefabricated, ready to use point cloud user interface which can be easily embedded in your own web apps. It exposes certain configuration parameters which let you fine tune the UI.

How to use?

plasio-ui depends on a few external dependencies to work and look right. It can automatically include all of these needed dependencies. If its loading stuff that's conflicting with your libraries, you can turn off external libraries loading and manually supply these dependencies.

The latest version of hosted plasio-ui is available at:

https://cdn.entwine.io/plasio-ui/0.3.7/plasio-ui.js

Express Mode

In this mode plasio-ui sets up everything for you, just include the library from the CDN and create the UI.

    plasioUI = plasio_ui.core.createUI(document.getElementById("app"), {
        includeExternalDependencies: true,
        googleMapsAPIKey: "AIzaSyAUWT5-vsCeQb1vYYamCw-RFvKTzLlY9iU",
        useBrowserHistory: true,

        colorSources: [
         ["local://ramp?field=Z", "Elevation"],
         ["local://ramp?field=Z&start=#FF0000&end=#00FF00", "Elevation RED -> GREEN"],
         ["local://ramp?field=Z&start=#FFFFFF&end=#0000FF", "Elevation WHITE -> BLUE"],
         ["local://color", "Color"],
         ["local://field-color?field=Classification", "Classification"],
         ["local://ramp?field=Intensity", "Intensity"],
         ["local://field-color?field=OriginId", "Origin ID"],
         ["local://field-color?field=point-source-id", "Point Source ID"]
       ]
    });

Note the includeExternalDependencies option (true by default, mentioned for verbosity), this option turns on external dependencies inclusion. This is all you need to get the UI up and running in express mode.

Advanced Mode

Advanced configuration is enabled when includeExternalDependencies is set to false. In this mode, you include external dependencies yourself. plasio-ui relies on a few libraries to work right:

You'd have to include the styles and javascript for each of these dependencies for plasio-ui to work right. Here's how the CSS inclusions would look like (they go in your HEAD tag):

    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/css/bootstrap.min.css" type="text/css">
    <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.4.0/css/font-awesome.min.css">
    <link href="https://cdnjs.cloudflare.com/ajax/libs/noUiSlider/8.2.1/nouislider.min.css" rel="stylesheet" type="text/css">

Scripts would look something like (it is recommended that these are placed at the bottom of the BODY tag):

<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.1.4/jquery.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/noUiSlider/8.2.1/nouislider.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/react/0.14.4/react.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/react/0.14.4/react-dom.min.js"></script>
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.5/js/bootstrap.min.js"></script>
<script type="text/javascript" src="https://maps.googleapis.com/maps/api/js?key={{YOUR GOOGLE MAPS KEY}}&libraries=places"></script>
<script src="https://cdn.entwine.io/plasio-ui/latest/plasio-ui.js"></script>

Remember to substitute in your Google Maps API key. You should then be good to go:

    plasioUI = plasio_ui.core.createUI(document.getElementById("app"), {
        includeExternalDependencies: false,
        useBrowserHistory: true,
        // in case the browser url is empty, use the following resource as fallback
        server: "http://devdata.greyhound.io/",
        resource: "nyc",
    });

The includeExternalDependencies value is false here.

Resources

Plasio-ui will try to read a file named resources.json which should be placed right alongside the HTML page hosting plasio-ui. This resource file is a list of servers/resources and some default parameters that go along with them (which brush to use etc.). The file looks like this:

{
  "servers": {
    "items": [
      {
        "url": "c[0-7].greyhound.io",
        "name": "cache.greyhound.io"
      }
    ]
  },
  "resources": {
    "defaults": {
      "server": "cache.greyhound.io"
    },
    "items": [
      {
        "name": "autzen",
        "displayName": "Autzen",
        "params": {
          "c0s": "local://color"
        }
      }
  }
}

Here we are defining a list of servers (which are then referred to in the resources section). Each resource then has the name of the resource, the display name and any initial query parameters you may wish to apply (here its setting c0s channel 0 source to local color). The resources.defaults section are the defaults values which are copied into each item under resources.items.

Self-hosting plasio-ui

It is recommended that you refer to plasio-ui on the provided CDN location. If that wouldn't work for you, pick the latest version from under the dist/ directory and extract it somewhere your web-page can access it. You would still just need to directly include plasio-ui.js. It will find all needed dependencies as long as you don't mess with the directory structure from the zip archive.

Configuring the UI

The createUI function accepts two parameters:

let ui = plasio_ui.core.createUI(divElement, options);

The following options are accepted:

UI Loading

  • includeExternalDependencies - Default: true. plasio-ui creates style/script tags to include needed dependent libraries, this option will also make it include external 3rd party dependencies like bootstrap, font-awesome etc.
  • ignoreDependencies - You may specify the 3rd libraries you don't want plasio-ui to load. This value must be an array with the libraries to ignore. You can use one or more of the following values: bootstrap, noUiSlider, jquery or font-awesome.
  • googleMapsAPIKey - When includeExternalDependencies is true, this value is used to query Google Maps API results.

UI/Renderer configuration

Option Default Description
allowGreyhoundCredentials false Requests binary data from greyhound service with withCredentials flag set to true. Note that this will most likely only work when your UI and data are hosted on the same domain, or you have the appropriate CORS headers set on your greyhound server.
availableResources Predefined default resources. When the resource switcher panel is visible, this array of resources define what resources should be listed.
bindKeyHandlers false This options installs global keyboard hooks which control certain aspects of the UI. This is not recommended when you're trying to embed plasio-ui in your own UI. The hooks are installed on the bubble up phase of event handlers, so it would still be possible to override the offending keystrokes in your own control.
brand speck.ly The brand to show in the application bar.
colorChannelRules The color channel rules to use to determine a good candidate for color source for the default color channel. See discussion below on how this process works.
colorSources You need at least one color source. You can specify any number of color sources. These sources will become available as the color channels for user to choose from. See details below. The first color source is used as default when no default channel information is available (e.g. from the URL).
credits No credits The credits property should be an object which could optionally have three fields in it: poweredBy, cachingProvider and backendProvider, these properties appear in the Information pane after all the point cloud information.
defaultColorChannelIndex 0 When the color channel information is not available (e.g. from the URL), plasio-ui will choose a default color channel so that the point cloud doesn't look all black. This option controls which color channel is used as default under this scenario. This value is the index of a pair in the specified colorSources property.
hiddenPanes All panes visible Selectively hide one or more panes you don't want to display. This field is an array of panes you want to hide. Array elements could have values: rendering-options, channels, point-manipulation, inundation-plane, information, local-settings and switch-resource. Note that, hiding a pane doesn't disable the functionality a pane offers, it merely doesn't let the user interact with or change the properties associated with a pane. E.g. hiding the channels pane doesn't disable channel functionality
includeExternalDependencies true When set to true, plasio-ui will automatically include all needed 3rd party dependencies. If this flag is false, you would need to specify all the required dependencies.
rememberUIState false When turned on, plasio-ui will employ web-browser local storage to store UI state (opened windows, certain preferences) per point cloud resource. When the users return to the same pipeline, they see the UI as they left it.
resources null When specified, plasio-ui will read available resources information from the provided option and won't reach out to resources.json. The format needs to be identical to resources.json file.
filters null When specified, plasio-ui will read available filters information from the provided option and won't reach out to filters.json. The format needs to be identical to filters.json file.
showPanels true Shows collapsible panels to the left.
showCompass true Shows the compass widget at bottom right corner of the render area.
showApplicationBar true Shows the application bar on top of the render area.
showSearch true Shows the little search icon on the right end of the application bar, which triggers a search dropdown for region local searches. This value is only considered when the application bar is visible, i.e. showApplicationBar is true.
useBrowserHistory false Manages browser history so that you can use the back and forward button to navigate through the renderer's state. Please note that for now, plasio takes over the browser URL, so unless you're making a full screen viewer, stay away from this option.

E.g. to create a bare bone viewer without any of the UI components you could create a renderer like:

  let ui = plasio_ui.core.createUI(divElement,  {
      useBrowserHistory: true,
      showPanels: false,
      showApplicationBar: false,
      colorSources: [ ... ]
  });

Or to create a renderer to view a point cloud without messing around with the browser history:

  let ui = plasio_ui.core.createUI(divElement,  {
      server: "my.hostname.com",
      resource: "such-point-cloud",
      showPanels: false,
      showApplicationBar: false,
      colorSources: [ ... ]
  });

Configuring Color Sources

Color sources are specified as an array of pairs. The first element of each pair is the brush description and the second element is a user friendly name for the source.

Several inbuilt configurable color brushes are provided. There are two kinds of brushes:

  • local - The color information is generated locally using the point description available, These sources start with local:// prefix.
  • remote - The color information is fetched remotely, usually from a tiling imagery source. These sources start with remote:// prefix.

Local Brushes

Local brushes use the available point information to compute a color. Some of the local sources available are:

Brush Name Description Parameters
ramp Computes a ramped color on the given field. field [REQUIRED] - e.g. field=Z or field=Intensity
start - The start color e.g.#FF0000.
end - The ending color e.g. #00FF00.
field-color Assigns a random color to each unique value. field [REQUIRED] - e.g. field=Classification
color Use the color from Red, Green and Blue color channels. No arguments

The user interface will provide appropriate controls to adjust the ramping stop points and histograms over Z values and Intensity values.

Remote Sources

The remote color brushes use satellite imagery to paint points. At this point only one remote brush is supported:

Brush Name Description Parameters
imagery Fetches remote imagery and overlays it on points. url [REQUIRED] - e.g. url=https://.../{x}/{y}/{z} - The placeholders {x}, {y} and {z} are required and will be substituted when querying imagery. Remember to URL encode the URL.

Example

Here is an example of setting color sources:

colorSources: [
     ["remote://imagery?url=" + encodeURIComponent("http://suchurl.com/images/tiles/{{z}}/{{y}}/{{x}}.jpg"), "Satellite Imagery"],
     ["local://ramp?field=Z", "Elevation"],
     ["local://ramp?field=Z&start=#FF0000&end=#00FF00", "Elevation RED -> GREEN"],
     ["local://ramp?field=Z&start=#FFFFFF&end=#0000FF", "Elevation WHITE -> BLUE"],
     ["local://color", "Color"],
     ["local://field-color?field=Classification", "Classification"],
]

Specifying Available Resources

When the switch-resource panel is available, you can specify the availableResources option to specify the list of resources to show. Plasio-ui will list them as direct links on the switch-resource panel. E.g.

...
availableResources: [
    ["Resource Name To Show", "resource-name", "server-address"],
    ["Nepal", "nepal-h", "http://myserver.com/resources"]
],
...

Hosting multiple Plasio UIs on a Single Page

This is work in progress and will be available soon.

Listening for and applying UI Changes

The plasio_ui.core.createUI function returns an object which has three methods: addChangeListener, removeChangeListener and apply.

To subscribe to any UI changes (including changes to the camera) setup a listener like:

let ui = plasio_ui.core.createUI(divElement);
let listenerId = ui.addChangeListener((v) => console.log('UI state is now:', v));

Your callback function will be called every time a change to the UI is made. The value passed to your function will carry the current state of the UI.

Please Note: The structure of the value passed to you can change from one version to another, but mostly when the major version number changes.

You can remove the listener like:

ui.removeChangeListener(listenerId);

You can apply a UI state object using the apply method:

let v = ...;
ui.apply(v);

This will update the current UI state to match the state specified by v.

Destroying Plasio UI

The plasio_ui.core.createUI function returns an object which has a destroy method. Calling this method will destroy the UI and empty out the div element it was hosted inside.

let ui = plasio_ui.core.createUI(divElement);
ui.destroy() // destroy the User Interface

Building

If you'd like to build your own version of speck.ly, run the following command (docker required):

bash scripts/docker-prod-staging-build.sh

This will use docker to build a version of speck.ly and place it in a directory named speck.ly under project root (location where you run this script from).