Merges terrain tiles together from 256 to 512 and buffered sizes
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gitignore
LICENSE.md Create LICENSE.md Mar 20, 2018
Pipfile Rewrite Zaloa to use Flask+Zappa to match Tapalcatl-py Jul 17, 2018
Pipfile.lock Rewrite Zaloa to use Flask+Zappa to match Tapalcatl-py Jul 17, 2018
README.md
circle.yml Fix tests? Jul 17, 2018
config.py Rewrite Zaloa to use Flask+Zappa to match Tapalcatl-py Jul 17, 2018
server.py Rewrite Zaloa to use Flask+Zappa to match Tapalcatl-py Jul 17, 2018
test.py Fix flake8 errors Jul 17, 2018
wsgi_server.py Rewrite Zaloa to use Flask+Zappa to match Tapalcatl-py Jul 17, 2018
zaloa.py

README.md

Zaloa

Zaloa takes input terrain tiles, and merges them together.

It is designed to be run as middleware to dynamically generate alternate tile sizes from 256px sources.

Sizes and tilesets

Zaloa uses two tilesets as its source:

  1. terrarium
  2. normal

Supports 512, and buffered variants of 256, namely 260 and 516. The variants have a 2 pixel buffer on each edge.

Tile Generation

The larger tiles are generated by sourcing the relevant neighbors from the 256px sources.

In the diagrams below, o is the source tile, and the xs represent the neighbors used.

512

o x
x x

260

x x x
x o x
x x x

516

x x x x
x O o x
x o o x
x x x x

Edge Cases

When on the "edge", there isn't a neighboring tile to source. Zaloa's behavior is:

  • column edge: wrap around and use the tile from the other "side".

eg: The left neighbor of 2/0/2 will be 2/3/2

  • row edge: the source tile is "copied" into the necessary location.

eg: The top neighbor of 2/2/0 is 2/2/0 itself, ie the top 2 rows of pixels are re-used as the buffer.

Development

We use Pipenv to manage dependencies. To develop on this software, you'll need to get pipenv installed first. Once you have pipenv installed, you can install the dependencies:

pipenv sync

If you update the Pipfile or want to update the dependency versions, you can run pipenv install --dev. This recalculates all the dependency versions, so may throw up dependency version conflicts which aren't present in the existing Pipfile.lock.

With the dependencies installed, you can enter the virtual environment so your dependencies are used:

pipenv shell

Configuration

The important bits of configuration are set in config.py using environment variables:

Environment Variable Name Description
TILES_FETCH_METHOD (s3 or http) Specifies which method you want to use when requesting terrain tiles.
TILES_S3_BUCKET Specifies the S3 bucket to use when requesting terrain tiles (if the fetch method is s3).
TILES_HTTP_PREFIX Specifies the HTTP prefix to use when requesting terrain tiles (if the fetch method is http).

Running locally

Once you have the dependencies installed as described above, you can use the Flask command line tool to run the server locally.

FLASK_DEBUG=true FLASK_APP=wsgi_server.py flask run

The FLASK_ environment variables specified before the flask run command are used to enable debug mode (FLASK_DEBUG) and to tell Flask's command line helper where the app code is (FLASK_APP). You can also include the other environment variables from the Configuration section here, too. When I run this locally to develop I run:

AWS_PROFILE=nextzen \
FLASK_DEBUG=true \
FLASK_APP=wsgi_server.py \
TILES_FETCH_METHOD=s3 \
TILES_S3_BUCKET=elevation-tiles-prod \
flask run

Deploying

This server can run in a normal WSGI environment (on Heroku, with gunicorn, etc.) but it was designed with Lambda in mind. We use Zappa to coordinate the package and deploy to Lambda. To get this to lambda, I ran:

  1. Setup Zappa for your account and AWS environment:

    zappa init
    
  2. Ask Zappa to deploy to your environment:

    zappa deploy dev
    
  3. Once Zappa deploys your code, it will not work until you set the configuration variables mentioned in the Configuration section above. You can set those via your Zappa configuration file or on the AWS Lambda console.