Browse files

Update readme, add screenshot

  • Loading branch information...
1 parent 3c3f1a6 commit 8a144725d0e4e60f16003b23dc32bb8351a181ee @tmcw tmcw committed Nov 16, 2012
Showing with 45 additions and 43 deletions.
  1. +45 −43
  2. BIN screenshot.jpg
@@ -1,19 +1,14 @@
-iD - friendly JavaScript editor for OpenStreetMap
+# iD - friendly JavaScript editor for OpenStreetMap
-* iD is a JavaScript-based [OpenStreetMap]( editor.
+## Basics
+* iD is a JavaScript-based [OpenStreetMap]( editor.
* It's intentionally simple. This is not a 90% editor -
not even a 70% editor. It should let you do the most basic tasks while
not breaking other people's data. Nothing more. (Same goes for the code,
so go easy on the abstraction. :) )
-* Speaking of percentages, it's about 1% complete.
-* The licence of iD is [WTFPL](, though obviously, if you want to dual-license
- any contributions that's cool.
+## Architecture
* iD uses [d3js]( for graphics & managing databindings to the
map. There's a tiny tiled-map core, but the majority of the action is in
@@ -22,48 +17,55 @@ Architecture
in Javascript that can be transformed by actions and serialized back into
-Getting started
-* Fork it and start playing!
-* Read the [live docs](, generated from source every hour.
+## Getting started
+* Fork this project. We eagerly accept pull requests.
+* See [open issues in the issue tracker if you're looking for something to do](
* All the code is in js/iD.
+To run the code locally, just fork this project and run it from a local webserver.
+With a Mac, you can enable Web Sharing and drop this in your website directory.
+If you have Python handy, just `cd` into `iD` and run
+ python -m SimpleHTTPServer
-How it works
-The code works similarly to [Potlatch 2](,
-but with a bit less abstraction. So, we have:
+## How it works
-* Connection: stores, fetches and saves data. (iD/Connection.js)
-* Entity (Node, Way, Relation): the data objects. (iD/Entity.js)
-* EntityUI (NodeUI, WayUI): the rendered graphic elements. (iD/renderer/...)
-* Map: the displayed map on which EntityUIs are rendered. (iD/renderer/Map.js)
-* Controller: the heart of the app, which does its work via...
-* ControllerState: the current UI mode. ControllerStates decide what to do in
- response to mouse/keyboard events. (iD/controller/...)
-* UndoableAction: the code to actually change the data, as fired by
- ControllerStates. (iD/actions/...)
+The code inherits many elements from the [Potlatch 2](
+and [JOSM]( editors.
-The UI is much more modal than Potlatch 2. In particular there's a "draw shape"
-mode (the "Add road or shape" button) and an "edit object" mode. The directory
-structure of iD/controller reflects this.
+We store technical notes in []( The
+basic architecture is as follows:
-As well as the [live docs](, you'll find
-various notes and comments in the docs/ folder. Feel free to add to these.
+* Map: vector rendering, panning behaviors & zoom/center state
+* Tiles: receives map centers & draw tiles as a background for iD
+* Connection: requests `/map` data from osm, parses this data and delivers it to the Graph
+* Graph: stores a javascript object of `id -> osm object`
+* History: stores multiple graphs which represent undo states
-Getting started
-Most of the interesting code is in the ControllerStates, which live in
-iD/controller/. Each one corresponds to a UI mode (e.g. "drawing a way").
-Its EntityMouseEvent method takes the user's mouse event (e.g. "clicked on
-a node"), carries out any actions, and returns the new ControllerState
-(which might just be 'this', i.e. carry on with the current state).
+* Map has-a Tiles
+* Map has-a Connection
+* Map has-a History
+* History has-many Graphs
+## Coding tips
-Coding tips
+This project has a few basic guidelines for incoming code. The cardinal rules are:
-Come on in, the water's lovely. More help? Ping RichardF on IRC
-(, in #osm-dev or #osm), on the OSM mailing lists or at
+1. Soft tabs only
+2. Everything should pass [jshint]( without warning
+3. Never write bugs
+(you can write bugs). If you need a style guide, [AirBNB has a decent one.](
+Come on in, the water's lovely. More help? Ping RichardF or tmcw on IRC
+(``, in `#osm-dev` or `#osm`), on the OSM mailing lists or at
+## License
+iD is available under the [WTFPL](, though obviously, if you want to dual-license
+any contributions that's cool. It includes [d3js](, which BSD-licensed.
BIN screenshot.jpg
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 8a14472

Please sign in to comment.