Quickstart

Getting started with Entwine is easy with Docker. Pull the most recent image with docker pull connormanning/entwine. Let’s assume there’s data at ~/abc.laz, and we will output to ~/entwine/abc. Let’s build an Entwine index:

mkdir ~/entwine
docker run -it -v $HOME:/opt/data connormanning/entwine \
    build -i /opt/data/abc.laz -o /opt/data/entwine/abc

Now we have Entwine data at ~/entwine/abc. We could have also passed a wildcard input like -i /opt/data/directory-of-files/* for a larger dataset. Let’s take a look at our index using the Greyhound Docker image, which we can get with docker pull connormanning/greyhound. By default, the Greyhound container will search for Entwine data at /opt/data and listen on port 80, so let’s make some port/volume mappings and we should be close to viewing our Entwine output.

docker run -it -v $HOME/entwine:/opt/data -p 8080:8080 connormanning/greyhound

You may need to forward port 8080 from your docker virtual machine to your host OS; this post describes one way to do this on macOS. For the impatient, use this one-liner:

VBoxManage controlvm default natpf1 "greyhound,tcp,127.0.0.1,8080,,8080"

Now we have Greyhound ready to serve our data, we just need a client renderer to view it. Let’s hit the URL below, which will connect to our new local Greyhound resource.

http://speck.ly?s=http://localhost:8080/&r=abc

Now we should be viewing our dataset dynamically with progressive level-of-detail. Another client sample would be Potree, which we can try out with http://potree.entwine.io/data/custom.html?s=localhost:8080&r=abc.

Going further

The default settings are fine for many datasets, but Entwine provides many parameters to more finely control your indexing configuration. Check out docker run -it connormanning/entwine build for a list of command line overrides. We’ve already seen -i and -o. Some other highlights:

  • -r: Specify a dataset reprojection. If your data has no color and you reproject to EPSG:3857, speck.ly can overlay imagery tiles in real-time.
  • -t: Specify the number of indexing threads. The default is 9. If you have a monster machine like an EC2 c3.8xlarge instance, you can try 30. We recommend a number close to, but no greater than, the number of physical cores on the machine for optimal performance.
  • -f: Want to write a new dataset at the same location as a previous one? This option forces an overwrite.

If the command line overrides are insufficient, you can get developer-level control over the indexing parameters by passing a JSON configuration file, for example entwine build config.json. There is a commented template for this configuration file here.