# tzmap.js - Library for working with the geography of timezones in JavaScript

# Written in 2011 by L. David Baron <dbaron@dbaron.org>

# To the extent possible under law, the author(s) have dedicated all
# copyright and related and neighboring rights to this software to the
# public domain worldwide.  This software is distributed without any
# warranty.
#
# You should have received a copy of the CC0 Public Domain Dedication
# along with this software.  If not, see
# <http://creativecommons.org/publicdomain/zero/1.0/>.

This is tzmap.js, a library for working with the geography of time zones
from JavaScript.

This is a companion library to tz.js, providing the geography-related
features.  It is intended to support applications that want to map
locations (latitude/longitude pairs) to time zone names and applications
that want to draw maps of time zones.

It incorporates data from http://efele.net/maps/tz/ , "A set of
shapefiles for the TZ timezones", available under CC0.

Files currently in the distribution are:

  pyshp/

    The Python Shapefile Library (under its own license).

  shapefile-to-json.py

    Code to construct the JSON data needed by tzmap.js from the
    tzmap shapefiles.

The library has the goal of providing these basic functions:

 (1) Map a (lat,lon) pair to zero or one timezones.

 (2) Get the shape outlines for a given timezone to draw the boundaries
     of a TZ database timezone.

 (3) Merge the shape outlines for adjacent timezones in order to draw
     the boundaries of a set of adjacent timezones (eliminating edges
     that were between two merged zones).  This allows drawing maps
     showing the timezone lines at a given point in time, or maps
     showing the regions that have a summer time change within a
     specific period (perhaps coded by the day they change).

This has the following implications for data structures:

  For (1), we want a quick test that allows rapidly eliminating most
  timezones; this is done by storing the N/E/S/W edges of the smallest
  rectangle enclosing all of the zone's polygons.

  For (3), we want each polygon for the zone to be stored as a list of
  (segment, direction-on-segment) pairs, and each segment to know which
  one or two zones it separates.


Build instructions:

 * Download the tz_world_mp.zip file from
   http://efele.net/maps/tz/world/ and place it in ../tzmap/
   (or elsewhere, and adjust the path at the top of
   shapefile-to-json.py)

 * Run |make| to generate the output in output/

Note that https://github.com/dbaron/timezone-map is a project that uses
this library (and the one I wrote it for).  It's possible that some code
in that repository might make sense being moved in this library.