sunders/README.md

# Surveillance under Surveillance

Surveillance under Surveillance shows you cameras and guards — watching you — almost everywhere. You can see where they are located and, if the information is available, what type they are, the area they observe, or other interesting facts.

Different icons and colors give you a quick overview about the indexed surveillance entries. Click on those icons on the map to get the available information.

Icon | Description
---- | -----------
![Cameras][img_camall] | Camera — no further information
![Fixed cameras][img_fixedall] | Fixed camera — usually observing a limited area
![Panning cameras][img_panningall] | Panning camera — usually able to observe various areas
![Dome cameras][img_domeall] | Dome camera — usually observing a 360° area
![Guards][img_guardall] | Guard — e.g. an employee of a security service
![Automatic Licence Plate Recognition][img_traffic] | ALPR — Automatic Licence Plate Recognition

Color | Description
----- | -----------
![Public surveillance][img_redall] | Red background — observing a public outdoor area, accessable by everyone
![Outdoor surveillance][img_blueall] | Blue background — observing a private outdoor area, accessable only by authorized persons
![Indoor surveillance][img_greenall] | Green background — observing an indoor area
![Cameras, fixme][img_todo_camall]<br>![Dome cameras, fixme][img_todo_domeall]<br>![Guards, fixme][img_todo_guardall]<br>![Automatic Licence Plate Recognition, fixme][img_todo_traffic] | Yellow icon — camera or guard marked with a fixme key because it needs further attention

A running instance of this project can be visited at [https://sunders.uber.space/](https://sunders.uber.space/).

## Prerequisites

- [Docker](https://www.docker.com)

## Installation

To run Surveillance using docker, decide between development/testing or production deployments:

### Development/testing

1. Clone this repository

2. Run `docker compose -f docker-compose.yml -f docker-compose.dev.yml up` and wait for services to start up

3. Visit `http://localhost:8080/` in a browser; you should see an interactive OpenStreetMap

4. You can see most cameras on the map immediately; the `data_handler` background process continuously applies updates from OpenStreetMap which become visible after refrshing the page

5. Appending `-f docker-compose.dev.yml` applies these changes:

   - PHP won't supress any errors; to disable this, remove `return;` in `./web/www/sunders/config.php`

   - Making changes in the `web` will immediately apply them to the running containers; try modifying `web/www/sunders/index.php`

   - Making changes in the `data_handler` will immediately apply them to the running containers (try modifying `data_handler/utils/update_camera.sh`)

   - The host has access to database files at `./mariadb`
### Production

1. Close this repository

2. Hardern security by opening `docker-compose.yml` and modifying `MYSQL_PASSWORD` and `MYSQL_ROOT_PASSWORD`

3. Run `docker compose up` and wait for services to start up

3. Visit `http://localhost:8080/` in a browser; you should see an interactive OpenStreetMap

4. You can see most cameras on the map immediately; the `data_handler` background process continuously applies updates from OpenStreetMap which become visible after refrshing the page

## Surveillance nodes

Surveillance under Surveillance uses data from Openstreetmap contributors that is not visualized on the regular [Openstreetmap](https://www.openstreetmap.org/) site. If you like to add new cameras or guards or if you like to revise existing entries [use your existing OSM account](https://www.openstreetmap.org/login) or [create a new one](https://www.openstreetmap.org/user/new).

These are the most common key/value combinations to describe a surveillance node at Openstreetmap:

### Mandatory to display an icon on the map

Icon | Key | Value
---- | --- | -----
 | [`man_made`](https://wiki.openstreetmap.org/wiki/Key:man_made) | [`surveillance`](https://wiki.openstreetmap.org/wiki/Tag:man_made%3Dsurveillance)
![Public surveillance][img_red] | [`surveillance`](https://wiki.openstreetmap.org/wiki/Key:surveillance) | `public`
![Outdoor surveillance][img_blue] | [`surveillance`](https://wiki.openstreetmap.org/wiki/Key:surveillance) | `outdoor`
![Indoor surveillance][img_green] | [`surveillance`](https://wiki.openstreetmap.org/wiki/Key:surveillance) | `indoor`
![Camera][img_cam] | [`surveillance:type`](https://wiki.openstreetmap.org/wiki/Key:surveillance:type) | `camera`
![Fixed camera][img_fixed] | [`surveillance:type`](https://wiki.openstreetmap.org/wiki/Key:surveillance:type)<br>[`camera:type`](https://wiki.openstreetmap.org/wiki/Proposed_features/Extended_tags_for_Key:Surveillance#Camera) | `camera`<br>`fixed`
![Panning camera][img_panning] | [`surveillance:type`](https://wiki.openstreetmap.org/wiki/Key:surveillance:type)<br>[`camera:type`](https://wiki.openstreetmap.org/wiki/Proposed_features/Extended_tags_for_Key:Surveillance#Camera) | `camera`<br>`panning`
![Dome camera][img_dome] | [`surveillance:type`](https://wiki.openstreetmap.org/wiki/Key:surveillance:type)<br>[`camera:type`](https://wiki.openstreetmap.org/wiki/Proposed_features/Extended_tags_for_Key:Surveillance#Camera) | `camera`<br>`dome`
![Guard][img_guard] | [`surveillance:type`](https://wiki.openstreetmap.org/wiki/Key:surveillance:type) | `guard`
![Automatic Licence Plate Recognition][img_traffic] | [`surveillance:type`](https://wiki.openstreetmap.org/wiki/Key:surveillance:type) | `ALPR`

### Mandatory to draw camera's field of view

Key | Value
--- | -----
[`surveillance:type`](https://wiki.openstreetmap.org/wiki/Key:surveillance:type) | `camera`
[`camera:type`](https://wiki.openstreetmap.org/wiki/Proposed_features/Extended_tags_for_Key:Surveillance#Camera) | `fixed`
[`camera:direction`](https://wiki.openstreetmap.org/wiki/Proposed_features/Extended_tags_for_Key:Surveillance#Camera) | `0` - `360` (in degrees) or<br>`N` / `NE` / `E` / `SE` / `S` / `SW` / `W` / `NW`
[`camera:angle`](https://wiki.openstreetmap.org/wiki/Proposed_features/Extended_tags_for_Key:Surveillance#Camera) | `15` - `90` (in degrees)<br>from an almost horizontal view to a ground-pointed camera<br>default: 15°
[`height`](https://wiki.openstreetmap.org/wiki/Key:height) | `3` - `12` (in meters)<br>default: 5m

Example 1 | Example 2 | Example 3
--------- | --------- | ---------
![Field of view (direction: 90°, angle: 15°, height: 5m)][img_example1] | ![Field of view (direction: 90°, angle: 15°, height: 10m)][img_example2] | ![Field of view (direction: 90°, angle: 60°, height: 10m)][img_example3]
direction = 90°<br>angle = 15°<br>height = 5m | direction = 90°<br>angle = 15°<br>height = 10m  | direction = 90°<br>angle = 60°<br>height = 10m

### Optional

Key | Value
--- | -----
[`surveillance:zone`](https://wiki.openstreetmap.org/wiki/Key:surveillance:zone) | `bank` / `building` / `parking` / `shop` / `town` / `traffic`
[`camera:mount`](https://wiki.openstreetmap.org/wiki/Proposed_features/Extended_tags_for_Key:Surveillance#Camera) | `ceilling` / `pole` / `wall`
[`operator`](https://wiki.openstreetmap.org/wiki/Key:operator) | organization or person operating the camera
[`name`](https://wiki.openstreetmap.org/wiki/Key:name) | name of the camera
[`ref`](https://wiki.openstreetmap.org/wiki/Key:ref) | reference number of the camera
[`image`](https://wiki.openstreetmap.org/wiki/Key:image) | link to an externally hosted image that depicts the surveillance object

## Credits

* Surveillance under Surveillance is based on the phantastic [osmcamera](https://github.com/khris78/osmcamera) [CC-BY-SA / MIT / GPLv3 / WTFPL] project of [khris78](https://github.com/khris78).
* Furthermore it uses the v1.3.1 code of [Leaflet/Leaflet](https://github.com/Leaflet/Leaflet) [BSD-2-Clause].
* The map itself is the work of millions of [OpenStreetMap](https://www.openstreetmap.org/) [ODbL / CC BY-SA] contributors.
* The results of the web services [OpenStreetMap Nominatim](https://nominatim.openstreetmap.org/) [ODbL] and [GeoNames](https://www.geonames.org/) [CC BY 3.0] are used for location searching and for surveillance node statistics.
* Most of the icons are from [Font Awesome](http://fontawesome.io/) [SIL OFL 1.1 / MIT / CC BY 3.0].
* The font [Grabstein Grotesk](https://fontlibrary.org/de/font/grabstein-grotesk) [OLF] is used for the titles.


[img_red]: ./web/www/sunders/images/colorRed.png "Public surveillance"
[img_redall]: ./web/www/sunders/images/colorRedAll.png "Public surveillance"

[img_blue]: ./web/www/sunders/images/colorBlue.png "Outdoor surveillance"
[img_blueall]: ./web/www/sunders/images/colorBlueAll.png "Outdoor surveillance"

[img_green]: ./web/www/sunders/images/colorGreen.png "Indoor surveillance"
[img_greenall]: ./web/www/sunders/images/colorGreenAll.png "Indoor surveillance"

[img_cam]: ./web/www/sunders/images/cam.png "Camera"
[img_camall]: ./web/www/sunders/images/camAll.png "Cameras"
[img_todo_camall]: ./web/www/sunders/images/todo_camAll.png "Cameras, fixme"

[img_fixed]: ./web/www/sunders/images/fixed.png "Fixed camera"
[img_fixedall]: ./web/www/sunders/images/fixedAll.png "Fixed cameras"
[img_todo_fixedall]: ./web/www/sunders/images/todo_fixedAll.png "Fixed cameras, fixme"

[img_panning]: ./web/www/sunders/images/panning.png "Panning camera"
[img_panningall]: ./web/www/sunders/images/panningAll.png "Panning cameras"
[img_todo_panningall]: ./web/www/sunders/images/todo_panningAll.png "Panning cameras, fixme"

[img_dome]: ./web/www/sunders/images/dome.png "Dome camera"
[img_domeall]: ./web/www/sunders/images/domeAll.png "Dome cameras"
[img_todo_domeall]: ./web/www/sunders/images/todo_domeAll.png "Dome cameras, fixme"

[img_guard]: ./web/www/sunders/images/guard.png "Guard"
[img_guardall]: ./web/www/sunders/images/guardAll.png "Guards"
[img_todo_guardall]: ./web/www/sunders/images/todo_guardAll.png "Guards, fixme"

[img_traffic]: ./web/www/sunders/images/traffic.png "Automatic Licence Plate Recognition"
[img_todo_traffic]: ./web/www/sunders/images/todo_traffic.png "Automatic Licence Plate Recognition, fixme"

[img_example1]: ./web/www/sunders/images/fixed_z-17_d-90_a-15_h-5.png "Field of view (direction: 90°, angle: 15°, height: 5m)"
[img_example2]: ./web/www/sunders/images/fixed_z-17_d-90_a-15_h-10.png "Field of view (direction: 90°, angle: 15°, height: 10m)"
[img_example3]: ./web/www/sunders/images/fixed_z-17_d-90_a-60_h-10.png "Field of view (direction: 90°, angle: 60°, height: 10m)"