-
Notifications
You must be signed in to change notification settings - Fork 92
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #81 from bonkles-worldai/master
First update of upstream master (v3) into our own master branch.
- Loading branch information
Showing
1,062 changed files
with
50,495 additions
and
22,930 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,316 @@ | ||
This file documents efforts toward establishing a public API for iD. | ||
|
||
## URL parameters | ||
|
||
##### iD Standalone | ||
|
||
iD supports several URL parameters. When constructing a URL to a standalone instance | ||
of iD (e.g. `http://preview.ideditor.com/release/`), the following parameters are available | ||
**in the hash portion of the URL**: | ||
|
||
* __`background`__ - The value from a `sourcetag` property in iD's | ||
[imagery list](https://github.com/openstreetmap/iD/blob/master/data/imagery.json), | ||
or a custom tile URL. A custom URL is specified in the format `custom:<url>`, | ||
where the URL can contain the standard tile URL placeholders `{x}`, `{y}` and | ||
`{z}`/`{zoom}`, `{ty}` for flipped TMS-style Y coordinates, and `{switch:a,b,c}` for | ||
DNS multiplexing.<br/> | ||
_Example:_ `background=custom:https://{switch:a,b,c}.tile.openstreetmap.org/{zoom}/{x}/{y}.png` | ||
* __`comment`__ - Prefills the changeset comment. Pass a url encoded string.<br/> | ||
_Example:_ `comment=CAR%20crisis%2C%20refugee%20areas%20in%20Cameroon` | ||
* __`disable_features`__ - Disables features in the list.<br/> | ||
_Example:_ `disable_features=water,service_roads,points,paths,boundaries`<br/> | ||
_Available features:_ `points`, `traffic_roads`, `service_roads`, `paths`, `buildings`, `building_parts`, `indoor`, `landuse`, | ||
`boundaries`, `water`, `rail`, `pistes`, `aerialways`, `power`, `past_future`, `others` | ||
* __`gpx`__ - A custom URL for loading a gpx track. Specifying a `gpx` parameter will | ||
automatically enable the gpx layer for display.<br/> | ||
_Example:_ `gpx=https://tasks.hotosm.org/project/592/task/16.gpx` | ||
* __`hashtags`__ - Prefills the changeset hashtags. Pass a url encoded list of event | ||
hashtags separated by commas, semicolons, or spaces. Leading '#' symbols are | ||
optional and will be added automatically. (Note that hashtag-like strings are | ||
automatically detected in the `comment`).<br/> | ||
_Example:_ `hashtags=%23hotosm-task-592,%23MissingMaps` | ||
* __`id`__ - The character 'n', 'w', or 'r', followed by the OSM ID of a node, way or relation, respectively. Selects the specified entity and centers the map on it, ignoring the `map` parameter. Multiple comma-separated values are supported.<br/> | ||
_Example:_ `id=n1207480649` | ||
_Example 2:_ `id=n1207480649,n3334654948` | ||
* __`locale`__ - A code specifying the localization to use, affecting the language, layout, and keyboard shortcuts. The default locale is set by the browser.<br/> | ||
_Example:_ `locale=en-US`, `locale=de`<br/> | ||
_Available values:_ Any of the [supported locales](https://github.com/openstreetmap/iD/tree/master/dist/locales). | ||
* __`map`__ - A slash-separated `zoom/latitude/longitude`. This will have no effect if `id` is specified.<br/> | ||
_Example:_ `map=20.00/38.90085/-77.02271` | ||
* __`maprules`__ - A path to a [MapRules](https://github.com/radiant-maxar/maprules) service endpoint for enhanced tag validation.<br/> | ||
_Example:_ `maprules=https://path/to/file.json` | ||
* __`offset`__ - Background imagery alignment offset in meters, formatted as `east,north`.<br/> | ||
_Example:_ `offset=-10,5` | ||
* __`photo_overlay`__ - The street-level photo overlay layers to enable.<br/> | ||
_Example:_ `photo_overlay=streetside,mapillary,openstreetcam`<br/> | ||
_Available values:_ `streetside` (Microsoft Bing), `mapillary`, `mapillary-signs`, `mapillary-map-features`, `openstreetcam` | ||
* __`presets`__ - A path to an external presets file or a comma-separated list of preset IDs. These will be the only presets the user may select.<br/> | ||
_Example:_ `presets=https://path/to/presets.json` | ||
_Example 2:_ `presets=building,highway/residential,highway/unclassified` | ||
* __`rtl=true`__ - Force iD into right-to-left mode (useful for testing). | ||
* __`source`__ - Prefills the changeset source. Pass a url encoded string.<br/> | ||
_Example:_ `source=Bing%3BMapillary` | ||
* __`walkthrough=true`__ - Start the walkthrough automatically | ||
|
||
##### iD on openstreetmap.org (Rails Port) | ||
|
||
When constructing a URL to an instance of iD embedded in the OpenStreetMap Rails | ||
Port (e.g. `http://www.openstreetmap.org/edit?editor=id`), the following parameters | ||
are available as **regular URL query parameters**: | ||
|
||
* __`map`__ - same as standalone | ||
* __`lat`__, __`lon`__, __`zoom`__ - Self-explanatory. | ||
* __`node`__, __`way`__, __`relation`__ - Select the specified entity. | ||
* __`background`__ - same as standalone | ||
* __`disable_features`__ - same as standalone | ||
* __`gpx`__ - same as standalone | ||
* __`maprules`__ - same as standalone | ||
* __`offset`__ - same as standalone | ||
* __`presets`__ - same as standalone | ||
* __`comment`__ - same as standalone | ||
* __`source`__ - same as standalone | ||
* __`hashtags`__ - same as standalone | ||
* __`locale`__ - same as standalone, but the default locale is set by the language settings in your OSM user account. | ||
* __`walkthrough`__ - same as standalone | ||
|
||
|
||
## CSS selectors | ||
|
||
iD has a documented and stable set of classes that can be used to apply style or | ||
attach behavior to the visual representation of map data via CSS selectors. | ||
These classes relate to the vocabulary of the OSM data model, a related geometric | ||
vocabulary established by iD, and to the tags present on OSM entities. | ||
|
||
### OSM Data Model classes | ||
|
||
An SVG element on the map to which an iD.Entity has been bound as a datum shall | ||
have a class with that datum's type, i.e. either `.node` or `.way`. (If and when | ||
we add visual representations for relations, `.relation` may also be valid.) | ||
|
||
The visual representation of a single entity may be composed of several elements, | ||
e.g. ways are composed of casing and stroke. Such elements will have a distinct class | ||
identifying the particular aspect of representation, e.g. `.casing` and `.stroke`. | ||
|
||
The particular type of SVG element (`path`, `circle`, `image` etc.) that is used to | ||
implement that visual representation is explicitly NOT part of the public API. Avoid | ||
naming specific tags in CSS selectors; as iD evolves, we may need to change what SVG | ||
elements we use in order to implement a particular visual style. | ||
|
||
### Geometric classes | ||
|
||
In addition to the OSM element vocabulary of nodes, ways, and relations, iD has | ||
established a related geometric vocabulary consisting of points, vertices, midpoints, | ||
lines, and areas. | ||
|
||
A **point** is a node that is not a member of any way. Elements representing points | ||
have a `.point` class. Since a point is always a node, they also have a `.node` class. | ||
|
||
A **vertex** is a node that is a member of one or more ways. Elements representing | ||
points have `.vertex` and `.node` classes. | ||
|
||
A **midpoint** is a virtual point drawn midway between two vertices along a way. | ||
Midpoints indicate the direction that the way, but can also be selected and dragged | ||
to create a new point along the way. Midpoints are classed with a `.midpoint` class. | ||
|
||
A **line** is a way that is not an area. Elements representing lines have a `.line` | ||
class. Since a line is also a way, they also have a `.way` class. | ||
|
||
An **area** is a way that is circular, has certain tags, or lacks certain other | ||
tags (see `iD.osmWay#isArea` for the exact definition). Elements representing areas | ||
have `.area` and `.way` classes. | ||
|
||
|
||
### Tag classes | ||
|
||
Elements also receive classes according to certain of the OSM key-value tags that are | ||
assigned to them. | ||
|
||
Tag classes are prefixed with `tag-` (see [`iD.svgTagClasses`](https://github.com/openstreetmap/iD/blob/master/js/id/svg/tag_classes.js) for details). | ||
|
||
#### Primary | ||
|
||
An element may be classed with at most one primary tag class based on its main OSM | ||
key -- "building", "highway", "railway", "waterway", etc. | ||
(e.g. `.tag-highway .tag-highway-residential`). | ||
|
||
#### Secondary | ||
|
||
An element may be classed with one or more secondary tag classes based on other | ||
interesting OSM keys -- "bridge", "tunnel", "barrier", "surface", etc. | ||
(e.g. `.tag-bridge .tag-bridge-yes`). | ||
|
||
#### Status | ||
|
||
An element may be classed with at most one status tag. Status tagging in OSM can | ||
be either key or value based, but iD attempts to detect most common lifecycle tagging | ||
schemes -- "construction", "proposed", "abandoned", "disused", etc. | ||
(e.g. `.tag-status .tag-status-construction`). | ||
|
||
#### Unpaved Surfaces (highways only) | ||
|
||
Most vehicular highways in OSM are assumed to have a smooth paved surface. A highway | ||
element may receive the special tag class `.tag-unpaved` if it contains certain OSM tags | ||
indicating a bumpy surface. | ||
|
||
### Special classes | ||
|
||
- A node that is a member of two or more ways shall have the `.shared` class. | ||
|
||
- A node that is an endpoint of a linear way shall have the `.endpoint` class. | ||
|
||
- Two or more nodes at identical coordinates shall each have an `.overlapped` class. (TODO) | ||
|
||
- Elements comprising the entity currently under the cursor shall have the `.hover` class. | ||
(The `:hover` psuedo-class is insufficient when an entity's visual representation consists | ||
of several elements, only one of which can be `:hover`ed.) | ||
|
||
- Elements that are currently active (being clicked or dragged) shall have the `.active` | ||
class. | ||
|
||
- Elements that are currently selected shall have the `.selected` class. | ||
|
||
|
||
## Customized Deployments | ||
|
||
iD may be used to edit maps in a non-OpenStreetMap environment. This requires | ||
certain parts of the iD code to be replaced at runtime by custom code or data. | ||
|
||
iD is written in a modular style and bundled with [rollup.js](http://rollupjs.org/), | ||
which makes hot code replacement tricky. (ES6 module exports are | ||
[immutable live bindings](http://www.2ality.com/2015/07/es6-module-exports.html)). | ||
Because of this, the parts of iD which are designed for customization are exported | ||
as live bound objects that can be overriden at runtime _before initializing the iD context_. | ||
|
||
### Services | ||
|
||
The `iD.services` object includes code that talks to other web services. | ||
|
||
To replace the OSM service with a custom service that exactly mimics the default OSM service: | ||
```js | ||
iD.services.osm = serviceMyOSM; | ||
``` | ||
|
||
Some services may be removed entirely. For example, to remove the Mapillary service: | ||
```js | ||
iD.services.mapillary = undefined; | ||
// or | ||
delete iD.services.mapillary; | ||
``` | ||
|
||
|
||
### Background Imagery | ||
|
||
iD's background imagery database is stored in the `iD.data.imagery` array and can be | ||
overridden or modified prior to creating the iD context. | ||
|
||
Note that the "None" and "Custom" options will always be shown in the list. | ||
|
||
To remove all imagery from iD: | ||
```js | ||
iD.data.imagery = []; | ||
``` | ||
|
||
To replace all imagery with a single source: | ||
```js | ||
iD.data.imagery = [{ | ||
"id": "ExampleImagery", | ||
"name": "My Imagery", | ||
"type": "tms", | ||
"template": "http://{switch:a,b,c}.tiles.example.com/{z}/{x}/{y}.png" | ||
}]; | ||
``` | ||
|
||
Each imagery source should have the following properties: | ||
* `id` - Unique identifier for this source (also used as a url paramater) | ||
* `name` - Display name for the source | ||
* `type` - Source type, currently only `tms` is supported | ||
* `template` - Url template, valid replacement tokens include: | ||
* `{z}`, `{x}`, `{y}` - for Z/X/Y scheme | ||
* `{-y}` or `{ty}` - for flipped Y | ||
* `{u}` - for quadtile scheme | ||
* `{switch:a,b,c}` - for parts of the url that can be cycled for connection parallelization | ||
|
||
Optional properties: | ||
* `description` - A longer source description which, if included, will be displayed in a popup when viewing the background imagery list | ||
* `overlay` - If `true`, this is an overlay layer (a transparent layer rendered above base imagery layer). Defaults to `false` | ||
* `zoomExtent` - Allowable min and max zoom levels, defaults to `[0, 22]` | ||
* `polygon` - Array of coordinate rings within which imagery is valid. If omitted, imagery is assumed to be valid worldwide | ||
* `overzoom` - Can this imagery be scaled up when zooming in beyond the max zoom? Defaults to `true` | ||
* `terms_url` - Url to link to when displaying the imagery terms | ||
* `terms_html` - Html content to display in the imagery terms | ||
* `terms_text` - Text content to display in the imagery terms | ||
* `best` - If set to `true`, this imagery is considered "better than Bing" and may be chosen by default when iD starts. Will display with a star in the background imagery list. Defaults to `false` | ||
|
||
For more details about the `iD.data.imagery` structure, see | ||
[`update_imagery.js`](https://github.com/openstreetmap/iD/blob/master/data/update_imagery.js). | ||
|
||
|
||
### Presets | ||
|
||
iD's preset database is stored in the `iD.data.presets` object and can be overridden | ||
or modified prior to creating the iD context. | ||
|
||
The format of the `presets` object is | ||
[documented here](https://github.com/openstreetmap/iD/tree/master/data/presets#custom-presets). | ||
|
||
To add a new preset to iD's existing preset database. | ||
```js | ||
iD.data.presets.presets["aerialway/zipline"] = { | ||
geometry: ["line"], | ||
fields: ["incline"], | ||
tags: { "aerialway": "zip_line" }, | ||
name: "Zipline" | ||
}; | ||
``` | ||
|
||
To completely replace iD's default presets with your own: | ||
```js | ||
iD.data.presets = myPresets; | ||
``` | ||
|
||
To run iD with the minimal set of presets that only match basic geometry types: | ||
```js | ||
iD.data.presets = { | ||
presets: { | ||
"area": { | ||
"name": "Area", | ||
"tags": {}, | ||
"geometry": ["area"] | ||
}, | ||
"line": { | ||
"name": "Line", | ||
"tags": {}, | ||
"geometry": ["line"] | ||
}, | ||
"point": { | ||
"name": "Point", | ||
"tags": {}, | ||
"geometry": ["point"] | ||
}, | ||
"vertex": { | ||
"name": "Vertex", | ||
"tags": {}, | ||
"geometry": ["vertex"] | ||
}, | ||
"relation": { | ||
"name": "Relation", | ||
"tags": {}, | ||
"geometry": ["relation"] | ||
} | ||
} | ||
}; | ||
``` | ||
|
||
|
||
### Minimum Editable Zoom | ||
|
||
The minimum zoom at which iD enters the edit mode is configured using the `context.minEditableZoom()` accessor. The default value is 16. To change this initialise the iD context as: | ||
|
||
```js | ||
|
||
var id = iD.coreContext() | ||
.minEditableZoom(zoom_level) | ||
|
||
``` | ||
|
||
This should be set with caution for performance reasons. The OpenStreetMap API has a limitation of 50000 nodes per request. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,75 @@ | ||
## Release Checklist | ||
|
||
### Prerelease (several days prior) | ||
- Notify translators of impending release | ||
(https://www.transifex.com/projects/p/id-editor/announcements/) | ||
- Notify TomH | ||
|
||
### Prep | ||
- If you don't have a `transifex.auth` file in the root of your iD checkout, | ||
you'll need to create a Transifex account, ask @bhousel for admin rights | ||
on the iD project, and then create this file with contents like<br><pre> | ||
{"user": "yourusername", "password": "*******"}</pre>This file is not version-controlled and will not be checked in. | ||
|
||
### Update `iD` | ||
|
||
#### Update `2.x` branch | ||
```bash | ||
$ git checkout 2.x | ||
$ rm -rf node_modules/editor-layer-index/ | ||
$ npm install | ||
$ npm run imagery | ||
$ npm run all | ||
$ git add . && git commit -m 'npm run imagery' | ||
$ npm run translations | ||
$ git add . && git commit -m 'npm run translations' | ||
``` | ||
|
||
- Update `CHANGELOG.md` | ||
- Update version number in `modules/core/context.js`, `package.json` | ||
|
||
```bash | ||
$ git add . && git commit -m 'vA.B.C' | ||
$ git push origin 2.x | ||
``` | ||
|
||
#### Update and tag `release` branch | ||
```bash | ||
$ git checkout release | ||
$ git reset --hard 2.x | ||
$ npm run all | ||
$ git add -f dist/*.css dist/*.js dist/img/*.svg dist/mapillary-js/ dist/pannellum-streetside/ | ||
$ git commit -m 'Check in build' | ||
$ git tag vA.B.C | ||
$ git push origin -f release vA.B.C | ||
``` | ||
- Open https://github.com/openstreetmap/iD/tags | ||
- Click `•••` –> `Create Release` and link to `CHANGELOG.md` in `Describe this release` | ||
|
||
### Update `openstreetmap-website` | ||
|
||
#### Setup remotes (first time only) | ||
```bash | ||
$ git remote add osmlab git@github.com:osmlab/openstreetmap-website.git | ||
$ git remote add upstream git@github.com:openstreetmap/openstreetmap-website.git | ||
``` | ||
|
||
#### Sync master branches | ||
|
||
```bash | ||
$ git fetch --all | ||
$ git checkout master | ||
$ git reset --hard upstream/master | ||
$ git push osmlab master | ||
``` | ||
|
||
#### Create and push branch with the new iD version | ||
|
||
```bash | ||
$ git checkout -b iD-A.B.C | ||
$ bundle install | ||
$ rm -rf vendor/assets/iD/* && vendorer | ||
$ git add . && git commit -m 'Update to iD vA.B.C' | ||
$ git push osmlab | ||
``` | ||
- [Open a pull request](https://github.com/openstreetmap/openstreetmap-website/compare/master...osmlab:master) using the [markdown text from the changelog](https://raw.githubusercontent.com/openstreetmap/iD/master/CHANGELOG.md) as the description |
Oops, something went wrong.