Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 102 lines (79 sloc) 6.872 kb
2315080 @rviscomi version 1.0
authored
1 Red Dwarf
bfa1c07 @rviscomi Initial commit
authored
2 =========
3
2315080 @rviscomi version 1.0
authored
4 ![trunk8 heatmap](http://jrvis.com/red-dwarf/img/trunk8-heatmap.jpg)
5
6 About
7 -----
8 **Red Dwarf** is a heatmap visualization of GitHub repository stargazers.
9
c802131 @rviscomi update demo to red-dwarf page
authored
10 Play with the [live demo](http://jrvis.com/red-dwarf/?rel=github).
2315080 @rviscomi version 1.0
authored
11
12 How it Works
13 ------------
ca3f491 @rviscomi privacy section, fixed typos
authored
14 Red Dwarf uses the GitHub API to determine the locations of people who have starred a given repository. Then, using the Google Maps API, these locations are translated into geocoordinates and fed into a heatmap. The result is a beautiful and detailed visualization of global positions of a repository's stargazers.
15
2315080 @rviscomi version 1.0
authored
16 Getting Started
17 ---------------
18 Red Dwarf depends on Google Maps for geocoding and mapping. You must get a [Google Maps API key](https://developers.google.com/maps/documentation/javascript/tutorial#api_key) to access these services.
19
20 Usage
21 -----
a0a303d @rviscomi link to Google API under Usage
authored
22 Import the Google Maps JavaScript API. Appending `libraries=visualization` to the source path will ensure that you have the heatmap library available. Replace `YOUR_KEY` with the API key [provided to you by Google](https://developers.google.com/maps/documentation/javascript/tutorial#api_key).
df807de @rviscomi how to import Maps API
authored
23
24 ```html
25 <script src="http://maps.googleapis.com/maps/api/js?key=YOUR_KEY&sensor=false&libraries=visualization"></script>
26 ```
27
7b44d10 @rviscomi fix README local links
authored
28 Instantiate a new RedDwarf object, the constructor of which accepts a configuration object (see [Settings](#settings)).
2315080 @rviscomi version 1.0
authored
29
30 ```js
31 var stars = new RedDwarf({
32 user: config.user,
33 repository: config.repository,
34 map_id: config.map_id
35 });
36 ```
37
38 Settings
39 --------
40 * **user** (required)
41 The GitHub user login of the repository owner.
42 * **repository** (required)
43 The GitHub repository name.
44 * **map_id** (required)
45 The ID of the HTML element in which to draw the map.
82cefc5 @rviscomi fix typos
authored
46 * **cache_location**
7b44d10 @rviscomi fix README local links
authored
47 The path (relative or absolute) of a JSON file containing precomputed geolocation data. If omitted, Red Dwarf will compute all data from scratch (see [Performance](#performance)). *Note: this file's contents are equivalent to the output of the [toJSON](#methods) method.*
2315080 @rviscomi version 1.0
authored
48 * **map_zoom** The initial zoom level of the heatmap. *Default: 2.* ([more info](https://developers.google.com/maps/documentation/javascript/tutorial#MapOptions))
1e267c0 @rviscomi clarified lat/lng defaults, moved privacy
authored
49 * **map_lat** The initial latitude position on which the heatmap is centered. *Default: `20`. (20 degrees north of the equator)* ([more info](https://developers.google.com/maps/documentation/javascript/tutorial#MapOptions))
50 * **map_lng** The initial longitude position on which the heatmap is centered. *Default: `0`. (Prime Meridian)* ([more info](https://developers.google.com/maps/documentation/javascript/tutorial#MapOptions))
51 * **map_type** The initial type of the heatmap: road, satellite, hybrid, or terrain. *Default: `"roadmap"`.* ([more info](https://developers.google.com/maps/documentation/javascript/tutorial#MapOptions))
2315080 @rviscomi version 1.0
authored
52
53 Methods
54 -------
82cefc5 @rviscomi fix typos
authored
55 * **toJSON** Returns a JSON representation of a mapping of string locations to geocodes, the number of repository stars, and a mapping of stargazers' user logins to their respective user objects.
2315080 @rviscomi version 1.0
authored
56
57 Events
58 ------
59 Red Dwarf will trigger each of the following events during processing. Arguments passed to the event handlers are listed below the event name (where applicable).
60
61 Event handlers are defined by including functions keyed by the respective event name in the settings object.
62
63 * **onRepositoryLoaded** Fired after successfully loading repository info from the GitHub API.
318869c @rviscomi fix formatting of event handler params
authored
64 * `data` The data object returned by GitHub.
67b1b62 @rviscomi issue #9 handle repo 404
authored
65 * **onRepositoryError** Fired after unsuccessfully loading repository info from the GitHub API.
66 * `message` The error message returned by GitHub.
2315080 @rviscomi version 1.0
authored
67 * **onCacheLoaded** Fired after successfully loading the JSON cache file.
68 * **onStargazersUpdated** Fired after processing a chunk of at most 100 repository stargazers.
318869c @rviscomi fix formatting of event handler params
authored
69 * `num_stargazers` The number of stargazers processed so far.
2315080 @rviscomi version 1.0
authored
70 * **onStargazersLoaded** Fired after successfully loading all stargazers.
71 * **onLocationUpdated** Fired after successfully loading a single stargazer's profile.
318869c @rviscomi fix formatting of event handler params
authored
72 * `num_resolved_stargazers` The number of stargazers whose profiles have been loaded so far.
73 * `num_stargazers` The total number of profiles to load.
2315080 @rviscomi version 1.0
authored
74 * **onLocationLoaded** Fired after successfully loading all stargazers' profiles.
75 * **onPointsUpdated** Fired after geocoding a chunk of at most 10 stargazer locations.
318869c @rviscomi fix formatting of event handler params
authored
76 * `num_resolved_points` The number of locations geocoded so far.
77 * `num_stargazers` The total number of locations to geocode.
2315080 @rviscomi version 1.0
authored
78 * **onPointsLoaded** Fired after successfully geocoding all locations and drawing the heatmap.
79
80 Performance
81 -----------
ca3f491 @rviscomi privacy section, fixed typos
authored
82 It's important to pre-cache the geolocation data because the Google Maps geocoding API places strict limits on the frequency of requests. Trial and error indicates that this limit is in the neighborhood of 40 requests per minute. This means a repository with 200 stars would take 5 minutes to get all geocoordinates. By default, Red Dwarf rate limits requests using a technique based on work by [Nicholas Zakas](http://www.nczonline.net/blog/2009/08/11/timed-array-processing-in-javascript/).
5192e44 @rviscomi modified performance explanation
authored
83
c5a796a @rviscomi fix typos, clarify
authored
84 Also note that repositories with many thousands of stargazers will likely hit usage limits on GitHub's API, because each stargazer's profile must be queried in order to get their location. Rate limiting is currently in development for this scenario.
5192e44 @rviscomi modified performance explanation
authored
85
c5a796a @rviscomi fix typos, clarify
authored
86 For these reasons, it's best to pre-cache as frequently as possible. This will prevent each page load from incurring the usage limit penalizations.
5192e44 @rviscomi modified performance explanation
authored
87
88 Red Dwarf will only make API calls for data not already in the cache.
2315080 @rviscomi version 1.0
authored
89
1e267c0 @rviscomi clarified lat/lng defaults, moved privacy
authored
90 Privacy
91 -------
92 Red Dwarf uses publicly-available stargazer information including login names and locations via the GitHub API. Locations are only derived from stargazers who have opted in to making their location public in their GitHub profile.
93
2315080 @rviscomi version 1.0
authored
94 MIT License
95 -----------
96 Copyright (c) 2012 Rick Viscomi (rviscomi@gmail.com)
97
98 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
99
100 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
101
102 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Something went wrong with that request. Please try again.