Skip to content
OpenStreetMap extension for Nginx Lua module
Branch: master
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.
debian
doc
misc
osm
tests
utils
.gitignore
Makefile
README.md

README.md

Name

lua-nginx-osm - Lua Tirex client driver for the ngx_lua based on the cosocket API

Status

Current version is 0.43, 21, October, 2013. This library is considered active development status.

Description

This Lua library is a Tirex client driver for the ngx_lua nginx module:

http://wiki.nginx.org/HttpLuaModule

This Lua library takes advantage of ngx_lua's cosocket API, which ensures 100% nonblocking behavior.

It also includes utility to handle metatile, URIs in Lua language. These utility is not depend on nginx, means pure lua implementation.

Note that at least ngx_lua 0.8.1 is required.

If you use Ubuntu Linux 12.04 (LTS) and after, there is a PPA(private package archive) for you. http://launchpad.net/~osmjapan/+archive/ppa Please see the above page for detail instructions.

Synopsis

lua_package_path "/path/to/lua-nginx-osm/?.lua;;";
lua_shared_dict osm_tirex 10m; ## mandatory to use osm.tirex module

server {
    location /example {
        content_by_lua '
            local tirex = require "osm.tirex"
            local tile = require "osm.tile"
            local data = require "osm.data"
            
            -- --------------------------------------------------
            -- check uri
            -- --------------------------------------------------
            local uri = ngx.var.uri
            local map = "example"
            local x, y, z = tile.get_cordination(uri, map, ".png")
            if not x then
                return ngx.exit(ngx.HTTP_FORBIDDEN)
            end
            
            -- check x, y, z range
            local max_zoom = 18
            local min_zoom = 5
            if not tile.check_integrity_xyzm(x, y, z, minz, maxz) then
                return ngx.exit(ngx.HTTP_FORBIDDEN)
            end
            
            -- check x, y, z supported to generate
            local region = data.get_region("japan")
            if not osm_tile.is_inside_region(region, x, y, z)
                -- try upstream server?
                return ngx.exit(ngx.HTTP_FORBIDDEN)
            end
            
            -- try renderd file
            local tilefile = tile.xyz_to_metatile_filename(x, y, z)
            local tilepath = tirex_tilepath.."/"..map.."/"..tilefile
            local png, err = tile.get_tile(tilepath, x, y, z)
            if png then
                ngx.header.content_type = "image/png"
                ngx.print(png)
                return ngx.OK
            end

            -- ask tirex to render it
            local ok = tirex.send_request(map, x, y, z)
            if not ok then
                return ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR)
            end

            -- get tile image from metatile
            local png, err = tile.get_tile(tilepath, x, y, z)
            if png then
                ngx.header.content_type = "image/png"
                ngx.print(png)
                return ngx.OK
            end
            return ngx.exit(ngx.HTTP_NOT_FOUND)
        ';
    }
}

Tile Methods

get_cordination

syntax: x, y, z = get_cordination(uri, map, ext)

Retrive x/y/z from uri path. If client GET uri /example/9/3/1.png then example map, z =9, x=3 and y=1 and extension is png.

xyz_to_metatile_filename

syntax: filename = osm.tile.xyz_to_metatile_filename(x, y, z)

Generate metatile filename from x/y/z cordination.

get_tile

syntax: png, err = osm.tile.get_tile(tilepath, x, y, z)

Get chunk of png image data of x/y/z cordination from metatile tilepath.

check_integrity_xyzm

syntax: ok = osm.tile.check_integrity_xyzm(x, y, z, minz, maxz)

Check whether x/y/z integrity. Tile x/y/z definition details are in https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames

check_integrity_xyz

syntax: ok = osm.tile.check_integrity_xyzm(x, y, z)

Same as check_integrity_xyzm() but don't check z range.

is_inside_region

syntax: include = osm.tile.is_inside_region(region, x, y, z)

Check x/y/z cordination is located and inside of region. region should be get from 'osm.data'

Data methods

syntax: * region = data.get_region("japan"))*

Get region definition table of argument country/area. This can use for is_inside_region() method.

Now provide following area/country data:

japan
asia
world

Tirex Methods

request

syntax: result = osm.tirex.request(map, x, y, z1, z2, priority)

Request enqueue command to rendering map 'map' with x/y/z1 cordination and priority. And also request to render in background between zoom z1 to z2. If request fails return nil.

When z1 == z2, just ask to render single tile.

cancel

syntax: result = osm.tirex.cancel(map, x, y, z1, z2, priority)

Request dequeue command to rendering map 'map' with x/y/z1 cordination and priority.And also request to cancel in background between zoom z1 to z2. If request fails return nil.

ping

syntax: result = osm.tirex.ping()

Request ping command. If request fails return nil.

Obsolete functions

send_request

syntax: result = osm.tirex.send_request(map, x, y, z)

Request enqueue command to rendering map 'map' with x/y/z cordination. If request fails return nil.

enqueue_request

syntax: result = osm.tirex.enqueue_request(map, x, y, z, priority)

Request enqueue command to rendering map 'map' with x/y/z cordination and priority. If request fails return nil.

dequeue_request

syntax: result = osm.tirex.dequeue_request(map, x, y, z, priority)

Request dequeue command to rendering map 'map' with x/y/z cordination and priority. If request fails return nil.

TODO

  • build more data definitions

  • and more on issue tracker.

Community

English Mailing List

The tile-serving mailing list is for English speakers. It is for all topic about tile serving development of openstreetmap, not only this project.

Web Chat

The osmfj-devel web chat is in Japanese/English. It is a chat room mainly for OSM Japan site and related software development.

Bugs and Patches

Please report bugs or submit patches by

  1. creating a ticket on the GitHub Issue Tracker,

  2. There are known problem that Tirex cannot response properly so we need to patch to tirex.

https://trac.openstreetmap.org/ticket/4869

If you use Tirex 0.4.1(original) or tirex-0.4.1ppa4 and below, you need to patch to tirex. Here is a patch file in misc/tirex-peer.diff.

Author

Hiroshi Miura miurahr@osmf.jp, OpenStreetMap Foundation Japan

Copyright and License

Hiroshi Miura, 2013 OpenStreetMap Foundation Japan, 2013

Distributed under GPLv3 License.

See Also

Bitdeli Badge

You can’t perform that action at this time.