# 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
# <https://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 https://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
   https://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.