Checkout   Browse   Changes

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353

% Complete documentation on the extended LaTeX markup used for Python% documentation is available in Documenting Python'', which is part% of the standard documentation for Python.  It may be found online% at:%%     http://www.python.org/doc/current/doc/doc.html\documentclass{manual}\title{Gheat}\author{Chad W. L. Whitacre}\usepackage{graphicx}% Please at least include a long-lived email address;% the rest is at your discretion.\authoraddress{	Zeta Design \&\ Development \\	\url{http://www.zetadev.com/software/gheat/} \\	Email: \email{\ulink{chad@zetaweb.com}{mailto:chad@zetaweb.com}}}\date{~~DATE~~} % update before release!%\date\today				% Use an explicit date so that reformatting				% doesn't cause a new date to be used.  Setting				% the date to \today can be used during draft				% stages to make it easier to handle versions.\release{~~VERSION~~}   % release version; this is used to define the				        % \version macro\begin{document}\maketitle\begin{abstract}\noindentGheat is a heatmap tile server for Google Maps. Gheat solves the problem ofpresenting data on a Google map when there is too much data to bewell-visualized by map markers.\end{abstract}\chapter{Introduction}\label{introduction}\ulink{Google Maps}{http://maps.google.com/} provides \ulink{a JavaScriptAPI}{http://code.google.com/apis/maps/} for integrating their maps with yourwebsite. The API includes calls to add markers on the map for various datapoints, but this only works when the number of markers placed on any given mapview is relatively small. Gheat solves the problem of presenting data on aGoogle map when there is too much data to be well-visualized by map markers. Itdoes so by using another of the JavaScript API's Google makes available,whereby additional tilesets can be layered on top of the base map tileset.(Google Maps works by splitting map imagery into 256x256 pixel tiles and thenknitting them together client-side.)Gheat runs as a standalone web application under the Aspen webserver. Data points are stored in a SQLite database, with each data point uniquely identifiedand timestamped. You modify the data in this database using a bundled script, run from the command line. The script reads data you provide in a CSV file and updates the database accordingly.Gheat only generates tiles containing data when requested, and it stores thesetiles on the filesystem for future use. On subsequent requests, if no datarelevant to the tile has changed then the image is served straight from thefilesystem. This saves considerable processing time. Most tiles will be empty,however, and Gheat precreates empty tiles for all zoom levels and serves thesame file for all empty tiles at a given zoom level. This saves considerabledisk space as well.Because of the cost of generating heatmaps, Gheat is probably not suitable forrealtime applications. But Gheat performs well when the underlying datasetevolves on a weekly or even daily basis.\chapter{Installation}\label{installation}\section{The Short Version}\begin{itemize}\item{Install \ulink{Python}{http://www.python.org/} (version 2.5 or newer).}\item{Install \ulink{Aspen}{http://www.zetadev.com/software/aspen/} (version 0.8 or newer).}\item{Download the Gheat distribution.}\item{Install \ulink{Pygame}{http://www.pygame.org/} or \ulink{PIL}{http://www.pythonware.com/products/pil/}.}\item{Start \program{aspen} in the Gheat distribution.}\item{Add a \ulink{GTileLayerOverlay}{http://code.google.com/apis/maps/documentation/reference.html#GTileLayerOverlay} to your embedded Google Map.}\end{itemize}\section{The Long Version}Gheat involves setting up a web application server, and then wiring up yourweb pages to make calls to that server via Google's JavaScript Maps API.The server side of Gheat has a few dependencies. The first is\ulink{Python}{http://www.python.org/}. You need version 2.5 or newer, becauseGheat requires the SQLite library, which was added to the standard library in2.5. There is also some 2.5 syntax in Gheat.  The second is\ulink{Aspen}{http://www.zetadev.com/software/aspen/}, which is a Pythonwebserver. Gheat is known to work with Aspen version 0.8. At this point you candownload and unpack the Gheat distribution, or check it out or export it fromthe Subversion repository. The next dependency is an imaging library; Gheatsupports both \ulink{Pygame}{http://www.pygame.org/} and\ulink{PIL}{http://www.pythonware.com/products/pil/} (if you install Pygame,you only need the imaging components). You can either install it locally in the\file{__} directory of the Gheat distribution (the\ulink{virtualenv}{http://pypi.python.org/pypi/virtualenv} tool is a great wayto manage this directory), or you can install it globally. The pygame backendis three or four times faster than PIL, but PIL is easier to install.  Thefunctionality is the same with both.Once all dependencies are satisfied, run the \program{aspen} program within theGheat distribution, which is an Aspen website root. The Gheat distributionincludes a sample database out of the box, so at this point you should be ableto hit the webserver now running on your machine and see a heatmap tile. Trythis URL:\ulink{http://localhost:8080/classic/4/4,6.png}{http://localhost:8080/classic/4/4,6.png}.\begin{figure}[htp]\includegraphics[bb=0 0 256 256]{img/4,6.png}\caption{A heatmap tile}\label{fig:tile}\end{figure}If you see an image like in Figure 2.1, then congratulations! You havesuccessfully installed the Gheat server.Once you get the server running, you need to set things up on the client side.First, you need to embed a \ulink{GoogleMap}{http://code.google.com/apis/maps/} on a web page. Then you need to definea new map layer with JavaScript code like this (see the Google Maps APIReference for\ulink{GTileLayer}{http://code.google.com/apis/maps/documentation/reference.html#GTileLayer}and\ulink{GTileLayerOverlay}{http://code.google.com/apis/maps/documentation/reference.html#GTileLayerOverlay}for full details):\begin{verbatim}bounds = new GLatLngBounds(new GLatLng(-90, -180), new GLatLng(90, 180));copyright = new GCopyright( 'your-org-copyright'                          , bounds                          , 0                          , "(c) 2008 Your Org <www.example.com>"                           );copyrights = new GCopyrightCollection();copyrights.addCopyright(copyright);gheat = new GTileLayer(copyrights, 10, 0);gheat.getTileUrl = function (tile, zoom) {  base = "http://localhost:8080";  color_scheme = 'classic';  url = base +'/'+ color_scheme +'/'+ zoom +'/'+ tile.x +','+ tile.y +'.png';  return url;}gheat.isPng = function () {return true;}gheat.getOpacity = function () {return 1.0;}\end{verbatim}Be sure to tweak the variables under \code{GCopyright} and \code{getTileUrl}for your situation. This code should run when the page loads, and then when themap is loaded, you need to add the overlay thus defined to the map, like this:\begin{verbatim}map.addOverlay(new GTileLayerOverlay(gheat));\end{verbatim}If it works, you will see the heatmap tiles loaded overtop of the underlyingGoogle Map, and you will feel pumped.\begin{seealso}\seelink{http://www.zetadev.com/software/aspen/}{Aspen}{The homepage for the Aspen webserver}\seelink{http://code.google.com/apis/maps/}{Google Maps}{The homepage for the Google Maps API}\seelink{http://www.pythonware.com/products/pil/}{PIL}{The homepage for the Python Imaging Library (PIL)}\seelink{http://www.pygame.org/}{Pygame}{The homepage for the Pygame library}\seelink{http://www.python.org/}{Python}{The homepage for the Python programming language}\seelink{http://pypi.python.org/pypi/virtualenv}{virtualenv}{The homepage for virtualenv, a tool to create isolated Python environments}\end{seealso}\chapter{Configuration}\label{configuration}Gheat responds to three configuration options. These are located in theINI-formatted file \file{__/etc/aspen.conf}, under a section named\code{[gheat]}. The three options are:\begin{tableiii}{l|l|l}{var}{Option}{Description}{Defaults}\lineiii{backend}{The backend library to use for image generation; either \code{Pygame} or \code{PIL} (case-insensitive). \code{Pygame} is three or four times faster than \code{PIL}, but \code{PIL} can be easier to install}{\code{Pygame} if available, then \code{PIL}}\lineiii{zoom_opaque}{The zoom level at and below which the master opacity will be 100\%}{-3}\lineiii{zoom_transparent}{The zoom level at and above which the master opacity will be 0\%}{15}\end{tableiii}Here is an example \file{aspen.conf} file:\begin{verbatim}[gheat]backend=PILzoom_opaque=-1zoom_transparent=11\end{verbatim}\section{Master Opacity}Google Maps' zoom level is zero-indexed, starting furthest out. As of thiswriting there are 20 zoom levels in use, so the highest available zoom level(closest in) is 19. The master opacity for Gheat will be scaled linearly between\var{zoom_opaque} and \var{zoom_transparent}. So, for example, with the defaultsettings (-3 to 15), the master opacities for each available zoom level are as follows.\begin{tableii}{l|l}{}{Zoom}{Opacity}\lineii{0}{82.8\%}\lineii{1}{77.3}\lineii{2}{71.9} \lineii{3}{66.4} \lineii{4}{60.5}\lineii{5}{55.1}\lineii{6}{49.6}\lineii{7}{44.1}\lineii{8}{38.7}\lineii{9}{33.2}\lineii{10}{27.3}\lineii{11}{21.9}\lineii{12}{16.4}\lineii{13}{10.9}\lineii{14}{5.5}\lineii{15}{0.0}\lineii{16}{0.0}\lineii{17}{0.0}\lineii{18}{0.0}\lineii{19}{0.0}\end{tableii}If \var{zoom_transparent} is less than or equal to \var{zoom_opaque}, theopacity will be 100\% for all zoom levels. The master opacity for each level ismultiplied by any alpha channel in the color scheme (see below) to determine thefinal opacity of the image.\section{Color Scheme}When you wire up the client side of Gheat, you choose which color scheme youwant to use (the process is described under Installation). The optionsbundled with Gheat are (the left image is the actual color scheme PNG; the rightimage is an example in use):\begin{figure}[htp]\includegraphics[bb=0 0 24 256]{color-schemes/classic.png}\includegraphics[bb=0 0 400 256]{img/cs-classic.png}\caption{classic}\label{fig:classic}\end{figure}\begin{figure}[htp]\includegraphics[bb=0 0 24 256]{color-schemes/fire.png}\includegraphics[bb=0 0 400 256]{img/cs-fire.png}\caption{fire}\label{fig:fire}\end{figure}\begin{figure}[htp]\includegraphics[bb=0 0 24 256]{color-schemes/omg.png}\includegraphics[bb=0 0 400 256]{img/cs-omg.png}\caption{omg}\label{fig:omg}\end{figure}\begin{figure}[htp]\includegraphics[bb=0 0 24 256]{color-schemes/pgaitch.png}\includegraphics[bb=0 0 400 256]{img/cs-pgaitch.png}\caption{pgaitch}\label{fig:pgaitch}\end{figure}\begin{figure}[htp]\includegraphics[bb=0 0 24 256]{color-schemes/pbj.png}\includegraphics[bb=0 0 400 256]{img/cs-pbj.png}\caption{pbj}\label{fig:pbj}\end{figure}You can produce your own color scheme. A color scheme is defined by a PNG ofheight 256 pixels. The image may be as wide as you like; only the first columnof pixels will be looked at. This first column is effectively a mapping ofintensities to four-channel colors (red, green, blue, and alpha). To use acustom color scheme, place your PNG file in the \file{__/etc/color-schemes/}directory of your Gheat installation, and use your PNG's filename without the\file{.png} extension as the token to wire into your JavaScript.The alpha channel of the pixels in the color scheme are multiplied with themaster opacity setting for the given zoom level (see above) to determine the final opacity of a given pixel in each tile.\begin{seealso}\seelink{http://www.zetadev.com/software/aspen/0.8/doc/html/aspen-conf.html}{\file{aspen.conf}}{Documentation for the \file{aspen.conf} file}\seelink{http://docs.python.org/lib/module-ConfigParser.html}{\module{ConfigParser}}{Thisdescribes the \file{INI} format used in \file{aspen.conf} (the\class{RawConfigParser} is used)}\end{seealso}\chapter{The db.py script}\label{db.py}The script at \file{__/bin/db.py} is used to manage the database at \file{__/var/points.db}. It's available subcommands are:\begin{tableii}{l|l}{var}{Subcommand}{Description}\lineii{clear}{Remove all points from the database}\lineii{count}{Print the number of points in the database to \file{stdout}}\lineii{delete}{Delete the database from the filesystem}\lineii{sync}{Update the database from the file at \file{__/var/points.txt}}\end{tableii}For the \var{clear}, \var{count}, and \var{sync} subcommands, the database willbe created if it does not exist. The default subcommand is \var{sync}. The \file{__/var/points.txt} file is a CSV-formatted file with three fields:\var{point id}, \var{latitude}, and \var{longitude}. The \var{point id} fieldcan be any string. If it is not unique within the \file{points.txt} file thenthe last point with a given \var{point id} will override any previous pointswith that same \var{point id}. Gheat uses the \var{point id} field to keeptrack of when points should be removed from the database, as well as whenpoints are updated, in order to tell when the tile cache ought to be flushed.The \var{latitude} and \var{longitude} fields must be floats. Multiple datapoints may have the same latitude and longitude in order to increase theintensity of that geographic point on the heatmap.The \var{sync} subcommand outputs a token for each point in the\file{points.txt} file:\begin{tableii}{l|l}{code}{Token}{Meaning}\lineii{.}{The point was not modified since the last time it was seen}\lineii{o}{The point was modified and has been updated}\lineii{O}{This is a new point}\end{tableii}The number of points deleted can be determined by using the \var{count}subcommand before and after the \var{sync} subcommand.\end{document}

Change log

r13 by whit537 on Apr 29, 2008   Diff
documentation
 Go to: /trunk/__/TODO /trunk/__/bin/speed-test.py /trunk/__/doc /trunk/__/doc/TODO /trunk/__/doc/html /trunk/__/doc/icons /trunk/__/doc/icons/blank.gif /trunk/__/doc/icons/blank.png /trunk/__/doc/icons/contents.gif /trunk/__/doc/icons/contents.png /trunk/__/doc/icons/index.gif /trunk/__/doc/icons/index.png /trunk/__/doc/icons/modules.gif /trunk/__/doc/icons/modules.png /trunk/__/doc/icons/next.gif /trunk/__/doc/icons/next.png /trunk/__/doc/icons/previous.gif /trunk/__/doc/icons/previous.png /trunk/__/doc/icons/pyfav.gif /trunk/__/doc/icons/pyfav.png /trunk/__/doc/icons/up.gif /trunk/__/doc/icons/up.png /trunk/__/doc/icons/zeta.ico /trunk/__/doc/tex /trunk/__/doc/tex/Makefile /trunk/__/doc/tex/color-schemes /trunk/__/doc/tex/gheat.tex /trunk/__/doc/tex/img /trunk/__/doc/tex/img/4,6.png ...nk/__/doc/tex/img/cs-classic.png /trunk/__/doc/tex/img/cs-fire.png /trunk/__/doc/tex/img/cs-omg.png /trunk/__/doc/tex/img/cs-pbj.png ...nk/__/doc/tex/img/cs-pgaitch.png /trunk/__/doc/tex/pgaitch.png /trunk/__/doc/tex/update.py /trunk/__/etc/color-schemes ...__/etc/color-schemes/classic.png ...__/etc/color-schemes/classic.psd ...nk/__/etc/color-schemes/fire.png ...nk/__/etc/color-schemes/fire.psd .../__/etc/color-schemes/master.psd /trunk/__/etc/color-schemes/omg.png /trunk/__/etc/color-schemes/omg.psd /trunk/__/etc/color-schemes/pbj.png .../color-schemes/peanut-butter.png .../color-schemes/peanut-butter.psd ...__/etc/color-schemes/pgaitch.png ...__/etc/color-schemes/pgaitch.psd /trunk/__/etc/color_schemes /trunk/__/gheat.js .../__/lib/python/gheat/__init__.py

Older revisions

All revisions of this file

File info

Size: 13979 bytes, 353 lines

File properties

svn:eol-style
native