diff --git a/documentation/Makefile b/documentation/Makefile new file mode 100644 index 00000000..dd9a492c --- /dev/null +++ b/documentation/Makefile @@ -0,0 +1,22 @@ +stylesheet = rocket-panda.css +styledir = /usr/local/share/asciidoctor/stylesheets +remote = h4:/home/maposmatic/maposmatic/www/static/documentation + +all: html pdf + +html: api-docs.html user-guide.html +pdf: api-docs.pdf user-guide.pdf + +%.html: %.txt + asciidoctor $< + +%.pdf: %.txt + asciidoctor-pdf $< + +clean: + rm -f *.html *.pdf *~ + +install: all + cp *.html ../www/maposmatic/templates + +.PHONY = html clean all install diff --git a/documentation/api-docs.txt b/documentation/api-docs.txt new file mode 100644 index 00000000..f77b104d --- /dev/null +++ b/documentation/api-docs.txt @@ -0,0 +1,469 @@ +MapOSMatic remote rendering API +=============================== +Hartmut Holzgraefe +:toc: +:toclevels: 2 +:source-highlighter: coderay +:data-uri: +:numbered: +v1, September 16th 2018 (Work in progress) + +MapOSMatic is a web frontend for the OCitySMap renderer, which uses +the Mapnik map rendering libary, Python and the CairoGraphics library +to create decorated single page maps and multi page atlas-like booklets. + +Originally this was a pure user centric web GUI, but recently a wish +for using the infrastructure with different web frontends did come up. + +So this HTTP API provides an alternative way to submit map rendering +requests, and to retrieve additional data that may be needed on the +way. + +Requests and results are submitted as JSON documents, with the +optional possibility to attach extra data files, like GPX tracks +or Umap user created maps. + +This documentation begins with describing the helper calls that +provide lists of possible choices for different data fields, +followed by the actual map rendering call and how to retrieve +rendering status and results, and ends with example programs +to access the API from different programming languages. + +API calls +--------- + +Paper Formats +~~~~~~~~~~~~~ + +Request URL +^^^^^^^^^^^ + +---- +https://api.get-map.org/apis/paper_formats +---- + +Example result +^^^^^^^^^^^^^^ + +---- +{ + "Best fit": { + "height": null, + "width": null + }, + "Din A4": { + "height": 297, + "width": 210 + }, + "US letter": { + "height": 279, + "width": 216 + } +} +---- + + + + +Layouts +~~~~~~~ + +Request URL +^^^^^^^^^^^ + +---- +https://api.get-map.org/apis/layouts +---- + +Example result +^^^^^^^^^^^^^^ + +---- +{ + "multi_page": { + "description": "A multi-page layout.", + "preview_url": "https://api.get-map.org/media/img/layout/multi_page.png" + }, + "plain": { + "description": "Full-page layout without index.", + "preview_url": "https://api.get-map.org/media/img/layout/plain.png" + }, + "single_page_index_bottom": { + "description": "Full-page layout with the index at the bottom.", + "preview_url": "https://api.get-map.org/media/img/layout/single_page_index_bottom.png" + }, + "single_page_index_side": { + "description": "Full-page layout with the index on the side.", + "preview_url": "https://api.get-map.org/media/img/layout/single_page_index_side.png" + } +} +---- + + + +Base Styles +~~~~~~~~~~~ + +Request URL +^^^^^^^^^^^ + +---- +https://api.get-map.org/apis/styles +---- + +Example output +^^^^^^^^^^^^^^ + +---- +{ + "CartoOSM": { + "annotation": "OpenStreetMap Carto standard style", + "description": "CartoCSS OSM standard style", + "preview_url": "https://api.get-map.org/media/img/style/CartoOSM.png" + }, + "GermanCartoOSM": { + "annotation": "German OSM style based on OSM Carto", + "description": "German OSM style", + "preview_url": "https://api.get-map.org/media/img/style/GermanCartoOSM.png" + } +} +---- + + +Overlay Styles +~~~~~~~~~~~~~~ + +Request URL +^^^^^^^^^^^ + +---- +https://api.get-map.org/apis/overlays +---- + + +Example output +^^^^^^^^^^^^^^ + +---- +{ + "OpenRailwayMap_Overlay": { + "annotation": "OpenRailwayMap overlay", + "description": "OpenRailwayMap rail line overlay", + "preview_url": "https://api.get-map.org/media/img/style/OpenRailwayMap_Overlay.jpg" + }, + "Scale_Bar_overlay": { + "annotation": "", + "description": "Map scale bar" + "preview_url": "https://api.get-map.org/media/img/style/Scale_Bar_overlay.jpg" + } + } +---- + + +Job Stati +~~~~~~~~~ + +Request URL +^^^^^^^^^^^ + +---- +https://api.get-map.org/apis/job_stati/ +---- + +Example result +^^^^^^^^^^^^^^ + +---- +{ + "0": "Submitted", + "1": "In progress", + "2": "Done", + "3": "Done w/o files", + "4": "Cancelled" +} +---- + + +Submitting a Job +~~~~~~~~~~~~~~~~ + +Request URL +^^^^^^^^^^^ + +---- +POST https://api.get-map.org/apis/jobs/ +---- + + +Expects render job named parameters as a JSON collection. + +Possible parameters: + +osmid:: ID of an object in the osm2pgsql +bbox_top:: +bbox_bottom:: +bbox_left:: +bbox_right:: Render area min. bounding box, may be extended to fit paper format +title:: Text to put into the title box (default: "Untitled API Request") +language:: locale to use for rendering (default: "en_US.UTF-8") +layout:: Map layout to use (default: "plain") +style:: Map base style to use (default: "CartoOSM") +overlays:: List of overlays to put on top of base style (default: None) +paper_size:: Paper size to use (default: "Din A4" 210x297mm²) +orientation:: Paper orientation: "portrait" or "landscape" (default: "portrait") +track_url:: URL pointing to a GPX track to download and print +umap_url:: URL pointing to an Umap export file do download and print + +It is also possible to upload GPX and Umap files directly using a multipart/form-data +POST request. In this case you have to submit the actual API JSON as a post parameter +named "json", and add file fields named "track" for a GPX track, or "umap" for an +Umap JSON export. + +After successfully submitting a request you can either poll the job result API every +once in a while until it either returns the "200 OK" status, or a 4xx error code. +Or you can redirect a web client to the human readable result page listed in the +returned "interactive" job parameter. + +Return codes +^^^^^^^^^^^^ + +202:: 'Accepted' when successfully submitted, "Location:" header will contain result URL +400:: 'Bad request' on request validation errors + +Example requests +^^^^^^^^^^^^^^^^ + +---- +Content-type: application/json + +{ + "title": "API Test", + "bbox_bottom": 52.00, + "bbox_left": 8.52, + "bbox_right": 8.50, + "bbox_top": 52.02 +} +---- + +---- +Content-Type: multipart/form-data; boundary=--XXXXXXXX + +--XXXXXXXX +Content-Disposition: form-data; name="json" + +{ + "title": "GPX Test", + "paper_size": "Din A1" +} +--XXXXXXXX +Content-Disposition: form-data; name="track"; filename="test.gpx" +Content-Type: application/gpx+xml + + + + + + GPX test + + + + + + + + +--XXXXXXXX-- +---- + +Example results +^^^^^^^^^^^^^^^ + +---- +HTTP/1.1 202 Accepted +[...] +Location: /api/jobs/36 +Content-Type: text/json + +{ + "bbox_bottom": 52.01, + "bbox_left": 8.52, + "bbox_right": 8.50, + "bbox_top": 52.02, + "id": 36, + "interactive": "https://api.get-map.org/maps/214" + "language": "en_US.UTF-8", + "layout": "plain", + "paper_height_mm": 297, + "paper_width_mm": 210, + "status": 0, + "styles": "CartoOSM" + "title": "API Test", +} +---- + +---- +HTTP/1.1 400 Bad Request +[...] +Content-Type: text/json + +{ + "error": { + "non_field_errors": [ + "No bounding box area or OsmID given" + ] + } +} +---- + + +Checking Job results +~~~~~~~~~~~~~~~~~~~~ + +Request Url +^^^^^^^^^^^ + +---- +https://api.get-map.org/apis/jobs/ +---- + +Return codes +^^^^^^^^^^^^ + +200:: 'OK' when request has been processed successfully +202:: 'Accepted' when rendering is still in progress, "Location:" header will contain same URL again +410:: 'Gone' when a request had been processed successfuly in the past, but result files have since been purged to free file system space +400:: 'Bad request' when a request failed to render + +Example result +^^^^^^^^^^^^^^ + +---- +HTTP/1.1 200 OK +[...] +Content-type: application/json + +{ + "bbox_bottom": 52.01, + "bbox_left": 8.53, + "bbox_right": 8.49, + "bbox_top": 52.02, + "files": + { + "8bit.png": "https://api.get-map.org/results//000215_2018-09-12_23-14_GPX-test.8bit.png", + "jpg": "https://api.get-map.org/results//000215_2018-09-12_23-14_GPX-test.jpg", + "pdf": "https://api.get-map.org/results//000215_2018-09-12_23-14_GPX-test.pdf", + "png": "https://api.get-map.org/results//000215_2018-09-12_23-14_GPX-test.png", + "svgz": "https://api.get-map.org/results//000215_2018-09-12_23-14_GPX-test.svgz" + } + "id": 215, + "language": "en_US.UTF-8", + "layout": "plain", + "paper_height_mm": 594, + "paper_width_mm": 841, + "queue_size": 0, + "status": 2, + "style": "CartoOSM", + "title": "GPX test" +} +---- + + + +Example code +------------ + + +PHP +~~~ + +All examples in this script use the `PEAR:HTTP_Request2` class for sending +HTTP requests and receiving server replies. + +Retrieve parameter choices +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Here we are using the `/paper_formats`, `/layouts`, `styles` and `overlays` +API calls to retrieve possible choices for all of these parameters, and +their textual description where available. + +.parameters.php +[source,php] +---- +include::code-snippets/parameters.php[] +---- + + +Submitting a simple request +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Now we are submitting a simple request, only setting the map title, +and the bounding box of the area to display. We do not check for +rendering to complete, but redirect the web client to the interactive +result URL given as `interactive` in the returned JSON data. + +This is the same result page as when you submit a map request manually +via the standard web user interface, so this approach is suitable for +interactive web applications: + +.simple-request.php +[source,php] +---- +include::code-snippets/simple-request.php[] +---- + + +Attaching a file +^^^^^^^^^^^^^^^^ + +Now, to make things more interesting, we are going to attach a GPX +file to our request. As the page title and the necessariy bounding +box to fit all track data can be extracted from the file, if it is +a valid GPX file, we do not need to pass any other data at all. + +.file-request.php +[source,php] +---- +include::code-snippets/file-request.php[] +---- + + + + +Wait for rendering to complete +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To have your application check for the rendering status yourself +you need to poll the `/jobs` status page, adding the job `id` +returned by the API. Please wait at least 15 seconds between +status poll requests. + +As long as the returned HTTP status is "202 Accepted" the +request is either currently being processed, or still +waiting in the job queue. + +When the job has completed successfully "200 OK" will be returned, +and the `files` object in the returned JSON result will contain +a hash of produced file formats, and under what URL each of them +can be retrieved. + +In the example we retrieve the PDF version, and start the users +preferred PDF viewer to present the result. + +.wait-for-result.php +[source,php] +---- +include::code-snippets/wait-for-result.php[] +---- + + +Python +~~~~~~ + +To be done + + +Javascript +~~~~~~~~~~ + +To be done, maybe. Due to the "same origin" restrictions +this is low on my list ... diff --git a/documentation/code-snippets/file-request.php b/documentation/code-snippets/file-request.php new file mode 100644 index 00000000..6f85e884 --- /dev/null +++ b/documentation/code-snippets/file-request.php @@ -0,0 +1,28 @@ +setMethod(HTTP_Request2::METHOD_POST) + ->addPostParameter('job', json_encode($data)) + ->addUpload('track', GPX_FILE, basename(GPX_FILE), 'application/gpx+xml'); + +$response = $request->send(); +$status = $response->getStatus(); + +echo "$status: ".$request->getBody()."\n"; + +if ($status < 200 || $status > 299) { + header("Content-type: text/plain"); + print_r($response->getBody()); + exit; +} + +$reply = json_decode($response->getBody()); + +echo "$status: ".$reply->interactive."\n"; diff --git a/documentation/code-snippets/parameters.php b/documentation/code-snippets/parameters.php new file mode 100644 index 00000000..7ee87e94 --- /dev/null +++ b/documentation/code-snippets/parameters.php @@ -0,0 +1,42 @@ +setMethod(HTTP_Request2::METHOD_GET); + + $response = $request->send(); + $status = $response->getStatus(); + + if ($status < 200 || $status > 299) { + echo "invalid HTTP response to '$url': $status\n"; + echo $response->getBody(); + exit(3); + } + + return json_decode($response->getBody()); +} + +echo "PAPER FORMATS:\n"; +$paper_formats = api_call('paper_formats'); +foreach ($paper_formats AS $name => $format) + printf("%-10s: %4dx%4d mm²\n", $name, $format->width, $format->height); + +echo "\nLAYOUTS\n"; +$layouts = api_call('layouts'); +foreach ($layouts as $name => $layout) + printf("%-25s: %s\n", $name, $layout->description); + +echo "\nSTYLES\n"; +$styles = api_call('styles'); +foreach ($styles as $name => $style) + printf("%-25s: %s\n", $name, $style->description); + +echo "\nOVERLAYS\n"; +$overlays = api_call('overlays'); +foreach ($overlays as $name => $overlay) + printf("%-25s: %s\n", $name, $overlay->description); diff --git a/documentation/code-snippets/simple-request.php b/documentation/code-snippets/simple-request.php new file mode 100644 index 00000000..4c377fc9 --- /dev/null +++ b/documentation/code-snippets/simple-request.php @@ -0,0 +1,30 @@ + 'PHP Test', + 'bbox_bottom' => 52.00, + 'bbox_top' => 52.02, + 'bbox_left' => 8.50, + 'bbox_right' => 8.52 + ]; + +$request = new HTTP_Request2(BASE_URL . "jobs"); + +$request->setMethod(HTTP_Request2::METHOD_POST) + ->setHeader('Content-type: application/json; charset=utf-8') + ->setBody(json_encode($data)); + +$response = $request->send(); +$status = $response->getStatus(); + +if ($status < 200 || $status > 299) { + header("Content-type: text/plain"); + print_r($response->getBody()); + exit; +} + +$reply = json_decode($response->getBody()); + +header("Location: " . $reply->interactive); diff --git a/documentation/code-snippets/wait-for-result.php b/documentation/code-snippets/wait-for-result.php new file mode 100644 index 00000000..e90d1591 --- /dev/null +++ b/documentation/code-snippets/wait-for-result.php @@ -0,0 +1,84 @@ +setMethod(HTTP_Request2::METHOD_GET); + + $response = $request->send(); + $status = $response->getStatus(); + + if ($status < 200 || $status > 299) { + echo "invalid HTTP response to '$url': $status\n"; + echo $response->getBody(); + exit(3); + } + + return array($status, json_decode($response->getBody())); +} + + +$data = ['title' => 'PHP Test', + 'bbox_bottom' => 52.00, + 'bbox_top' => 52.02, + 'bbox_left' => 8.50, + 'bbox_right' => 8.52 + ]; + +$request = new HTTP_Request2(BASE_URL . "jobs"); + +$request->setMethod(HTTP_Request2::METHOD_POST) + ->setHeader('Content-type: application/json; charset=utf-8') + ->setBody(json_encode($data)); + +$response = $request->send(); +$status = $response->getStatus(); + +if ($status < 200 || $status > 299) { + header("Content-type: text/plain"); + print_r($response->getBody()); + exit; +} + +$reply = json_decode($response->getBody()); + +echo $reply->interactive."\n"; + +$job_url = "/jobs/" . $reply->id; + + echo "waiting ... "; + sleep(15); + list($status, $reply) = api_GET($job_url); + + switch ($status) { + case 200: + $done = 1; + break; + case 202: + switch($reply->status) { + case 0: + echo "still in queue\n"; + break; + case 1: + echo "now being rendered\n"; + break; + default: + echo "unexpected status: ".$reply->status."\n"; + break; + } + break; + default: + die("unexpected HTTP status: $status"); + break; + } +} + +$pdf = basename($reply->files->pdf); +copy($reply->files->pdf, $pdf); + +system("xdg-open $pdf"); +rm($pdf); \ No newline at end of file diff --git a/documentation/img/gpx-result.png b/documentation/img/gpx-result.png new file mode 100644 index 00000000..fe2e7849 Binary files /dev/null and b/documentation/img/gpx-result.png differ diff --git a/documentation/img/gpx-selected.png b/documentation/img/gpx-selected.png new file mode 100644 index 00000000..b9f44d9d Binary files /dev/null and b/documentation/img/gpx-selected.png differ diff --git a/documentation/img/select-area.png b/documentation/img/select-area.png new file mode 100644 index 00000000..5b52244a Binary files /dev/null and b/documentation/img/select-area.png differ diff --git a/documentation/img/select-city.png b/documentation/img/select-city.png new file mode 100644 index 00000000..5eda075e Binary files /dev/null and b/documentation/img/select-city.png differ diff --git a/documentation/img/select-gpx.png b/documentation/img/select-gpx.png new file mode 100644 index 00000000..86bac077 Binary files /dev/null and b/documentation/img/select-gpx.png differ diff --git a/documentation/img/select-umap.png b/documentation/img/select-umap.png new file mode 100644 index 00000000..5530db4c Binary files /dev/null and b/documentation/img/select-umap.png differ diff --git a/documentation/img/step-layout.png b/documentation/img/step-layout.png new file mode 100644 index 00000000..588d5184 Binary files /dev/null and b/documentation/img/step-layout.png differ diff --git a/documentation/img/step-overlay.png b/documentation/img/step-overlay.png new file mode 100644 index 00000000..33d623b4 Binary files /dev/null and b/documentation/img/step-overlay.png differ diff --git a/documentation/img/step-papersize.png b/documentation/img/step-papersize.png new file mode 100644 index 00000000..ad0e3962 Binary files /dev/null and b/documentation/img/step-papersize.png differ diff --git a/documentation/img/step-progress-bar.png b/documentation/img/step-progress-bar.png new file mode 100644 index 00000000..7f60c5c7 Binary files /dev/null and b/documentation/img/step-progress-bar.png differ diff --git a/documentation/img/step-style.png b/documentation/img/step-style.png new file mode 100644 index 00000000..00c26350 Binary files /dev/null and b/documentation/img/step-style.png differ diff --git a/documentation/img/step-submit.png b/documentation/img/step-submit.png new file mode 100644 index 00000000..183c1631 Binary files /dev/null and b/documentation/img/step-submit.png differ diff --git a/documentation/img/umap-actual.png b/documentation/img/umap-actual.png new file mode 100644 index 00000000..f0937139 Binary files /dev/null and b/documentation/img/umap-actual.png differ diff --git a/documentation/img/umap-result.png b/documentation/img/umap-result.png new file mode 100644 index 00000000..c2292bfe Binary files /dev/null and b/documentation/img/umap-result.png differ diff --git a/documentation/img/umap-selected.png b/documentation/img/umap-selected.png new file mode 100644 index 00000000..571c465f Binary files /dev/null and b/documentation/img/umap-selected.png differ diff --git a/documentation/user-guide.txt b/documentation/user-guide.txt new file mode 100644 index 00000000..01159d6b --- /dev/null +++ b/documentation/user-guide.txt @@ -0,0 +1,296 @@ +MapOSMatic User Guide +===================== +Hartmut Holzgraefe +:toc: +v0.1, May 5th, 2018 +Work in progress + +:imagesdir: ./img +:data-uri: +:numbered: + +Overview +-------- + + + +Creating a map - step by step +----------------------------- + +The map creation form leads you through a series of steps that each +cover a specific step in the overal map creation workflow. Which +step you are in is visualized in an icon bullet bar. + +image:step-progress-bar.png[Select City,width=80%,pdfwidth=80%,align=center] + +You can only navigate between steps with the [Next] and [Back] buttons +though, as some steps depend on spefic input from previous steps. +So it is not possible to navigate between arbitrary steps by clicking +on the step icons. + +The [Next] button will appear whenever a valid choice was made in +the current step, the [Back] button is visible on all but the first +step. On the final step a [Generate Map] button is shown instead +of the [Next] button. + + +Select a map area or upload a file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +At the very beginning the map area to be rendered needs to be determined. +For this there are currently four alternatives, available as different +form tabs: + +* Directly select a rectangular area on an online map +* Use a city or place name to look up its boundaries in the OSM database +* Upload a GPX track, the map area will be the tracks bounding box +* Upload an Umap file, the map area will be determined by the contained data + +When uploading a file you can still select a different, e.g. smaller or larger, +map area afterwards. + + + +Directly Select Area +^^^^^^^^^^^^^^^^^^^^ + +image::select-area.png[Select Area,width=80%,pdfwidth=80%,align=center] + +Here you can select a rectangular map area. The map shown is a typical “slippy” online map, +on the left you have buttons for zooming in and out, a button to detect your current location, +and a search button to search for a place by name. + +By default the full visible map area is selected here, but you may also use the *[Select area]* +button to enable a more sophisticated area selection tool. + +When pressing the *[Select area]* button the user interface changes a bit, you'll now see a +highlighted rectangular area that marks the actual selected area. You can drag the four corners +of the rectangle around to change its shape and size, and you can move the complete area by +dragging it along by the dotted marker in its upper left corner. + +With *[Select area within current zoom]* you can make the full visible area the new selection, +and the *[Remove selection]* brings you back to the original mode. + +The four number fields below the map show the current min. and max. latitude and longitude +of your selected area. + +When you are satisfied with your selection you can use the *[>]* button on the right to move +on to the next form step. + + + +City Search +^^^^^^^^^^^ + +image:select-city.png[Select City,width=80%,pdfwidth=80%,align=center] + +On the “City search” tab you can enter a city or place name in the input field, if the administrative +borders of that city or place are known to OpenStreetMap these can be used to determine the map area +to use automatically. + +A dropdown below the field will show possible matches for your input as you type. Only the matches +that are printed in black are selectable. The matches printed in grey are either place nodes for +which no border information is available in OSM yet, or the place area is too large to be printed +with this web service. + + +Upload a GPX Track +^^^^^^^^^^^^^^^^^^ + +image::select-gpx.png[GPX Upload,width=80%,pdfwidth=80%,align=center] + +Here you can upload a GPX file containing GPS data and waypoints. The track, and all +named waypoints, will then be rendered on top of the base map. + +For now you can only select a single GPX file, support for multiple track files may +be added in the future. + +The upload form performs some basic checks, so it will complain when the uploaded +file is not in GPX format, or does not contain any usable tracks. + +Note that the file will be stored on the web server, and that the map generated from +it (but not the actual GPX file) will be visible to everyone. So do not upload any +sensitive data you don't want to to be seen in public, or that you don't have the +permission for to share it in public. + + +image::gpx-selected.png[GPX Preview,width=80%,pdfwidth=80%,align=center] + +Once a valid GPX file has been selected the form switches back to the area selection +tab, and will show a preview of the file contents and the optimal map area to display +all contained GPS data. + +If you want to render a different area, e.g. just a smaller part of the track, or a +larger area showing more context beyond the track area itself, you can change the +selection area accordingly. + + +image::gpx-result.png[GPX Render Result,width=80%,pdfwidth=80%,align=center] + +The actual final result of a rendered GPX track may look like the example to the left. + + + +Upload a Umap File +^^^^^^^^^^^^^^^^^^ + +Here you can upload a file exported from Umap, a service that lets you create online +maps with your own markers and drawings on top. We provide you with a way to also use +this fine tool to produce customized printed maps with your own data on top, and not +only online maps. + +To create an export file from a Umap you created you need to click on the +“Embed and Share” Icon on the left side of the Umap interface, and then use +“Download Data → Full map data” in the sidebar on the right hand size. + +The upload form performs some basic checks, so it will complain when the uploaded file +is not in Umap format, or does not contain any usable data. + +Only data directly added using the Umap drawing tools will be rendered for now. +Umap also allows to import external data on the fly, like data form CSV files, +or dynamic queries against an Overpass API Server, this kind of data is not +supported by this service yet though, and so will not be part of the generated +print map. + +Note that the file will be stored on the web server, and that the map generated from it +(but not the actual Umap file) will be visible to everyone. So do not upload any +sensitive data you don't want to to be seen in public, or that you don't have the +permission for to share it in public. + +image::umap-selected.png[Umap Preview,width=80%,pdfwidth=80%,align=center] + +Like with GPX uploads, once a valid Umap file has been selected for upload the form +will switch back to the area selection tab and will show a simplified preview of the +uploaded data. + +You can modify the selected area if you only want to show part of the Umap +information, or actually want to show it in a larger map context. + +image:umap-result.png[Umap Render Result,width=45%,pdfwidth=45%] +image:umap-actual.png[Umap Original Online Map,width=45%,pdfwidth=45%] + +An actually rendered Umap map may look like the example on the left hand side, +while the right hand side shows how the original online Umap looks like. +The results are not completely the same , especially when it comes to line stroke +width, but this is mostly due to difference in size an resolution of the target +devices, paper vs. screen. + + + +Select a paper layout +~~~~~~~~~~~~~~~~~~~~~ + +In this step you can choose between different paper layouts. + +image::step-layout.png[Umap Preview,width=80%,pdfwidth=80%,align=center] + +There are three different single page layouts, and one for multi page +booklets. + +The basic single page layout uses the full page for the map. + +The other two single page layouts add a street index to the +map, either on the side -- left side for left-to-write languages, +or right side for right-to-left languages like Arabic or Hebrew -- +or at the bottom. + +The multi page layout creates a multi page booklet with a title +page, an overview page, a collection of detail map pages, and +a street index. + +The preview on the right hand side changes with your selection, +it does not show the actual selected map area though. It is +just using pre-rendered examples to give you a rough idea +what each layout looks like. + + +Select a map style +~~~~~~~~~~~~~~~~~~ + +Here you can select the style of the base map. + +image::step-style.png[Umap Preview,width=80%,pdfwidth=80%,align=center] + +Style selections are grouped by specific themes, e.g. for +country specific styles. Only one base style can be selected. + +The preview on the right hand side again changes with your +selection, and only shows a fixed pre-defined map area, +not the area you actually chose, to give you a quick +rough idea what the chosen style looks lie. + +Optionally: Select map overlays +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Map overlays are rendered on top of the basemap. They can +either add decoration elements like a compas rose or scale +bar, or additional special interest map features like +hiking routes, fire hydrants or height contour lines. + +image::step-overlay.png[Umap Preview,width=80%,pdfwidth=80%,align=center] + +Overlay styles are also grouped by theme like the base styles, +but here you can select multiple overlay styles, not just one. + +The preview on the right only shows the last overlay you +selected, on top of the Black&White base style for better visibility +of the overlay additions, not a combination of all selected overlays. + + +Select paper size an orientation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In this step the minimal required paper size is calculated, +and you are given a choice of predefined paper formats that +are larger than this, plus a "best fit" option. + +image::step-papersize.png[Umap Preview,width=80%,pdfwidth=80%,align=center] + +You can also select the paper orientation here. The optimal +orientation is pre-selected automatically, but you can override +the default choice to fit your own needs. + +Select map title and language +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This is the final step before submiting the rendering job. +Here you can select a map title, the language for map +annotations, and optionally give your email address if +you want to be informed via mail when your request has +been processed. + +Also a quick summary of your choices is shown. + +image::step-submit.png[Umap Preview,width=80%,pdfwidth=80%,align=center] + +The map title is prefilled if you used the city selection +to specify the map area. If you uploaded a GPX or Umap +file the map title will also be prefilled if title information +was found in the uploaded file. + +The chosen language is used for the annotations and copyright +information at the bottom of the map, and for section titles +in the street index. In the German style it also influences +the language choice for actual map features, the other styles +still use a fixed language setting so far though. + +If you provide an email address you will be notified when +your rendering request has been processed successfully, or +ran into an error. The email address entered here will +only be stored for 48 hours, and will usually only be used +to send the result notification. In case of rendering errors +you may also receive feedback questions to help debugging +the problem, and in case of a bug fixed you will be informed +about a successful re-rendering of your request. + + +Map styles +---------- + + + + +Overlay styles +-------------- + + diff --git a/www/maposmatic/templates/maposmatic/base-parts/navbar.html b/www/maposmatic/templates/maposmatic/base-parts/navbar.html new file mode 100644 index 00000000..0f86c9d9 --- /dev/null +++ b/www/maposmatic/templates/maposmatic/base-parts/navbar.html @@ -0,0 +1,79 @@ +{% load i18n %} +{% load extratags %} + + diff --git a/www/maposmatic/templates/maposmatic/documentation-api.html b/www/maposmatic/templates/maposmatic/documentation-api.html new file mode 100644 index 00000000..d15bc881 --- /dev/null +++ b/www/maposmatic/templates/maposmatic/documentation-api.html @@ -0,0 +1,39 @@ +{% extends "maposmatic/base.html" %} + +{% comment %} + coding: utf-8 + + maposmatic, the web front-end of the MapOSMatic city map generation system + Copyright (C) 2012 David Decotigny + Copyright (C) 2012 Frédéric Lehobey + Copyright (C) 2012 Pierre Mauduit + Copyright (C) 2012 David Mentré + Copyright (C) 2012 Maxime Petazzoni + Copyright (C) 2012 Thomas Petazzoni + Copyright (C) 2012 Gaël Utard + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU Affero General Public License as + published by the Free Software Foundation, either version 3 of the + License, or any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License + along with this program. If not, see . +{% endcomment %} +{% load i18n %} +{% load extratags %} + +{% block body-class %}about{% endblock %} +{% block menu-about %}active{% endblock %} + +{% block title %}{% trans "User Guide" %}{% endblock %} +{% block page %} + +{% include "api-docs.html" %} + +{% endblock %} diff --git a/www/maposmatic/templates/maposmatic/documentation-user-guide.html b/www/maposmatic/templates/maposmatic/documentation-user-guide.html new file mode 100644 index 00000000..4a74098e --- /dev/null +++ b/www/maposmatic/templates/maposmatic/documentation-user-guide.html @@ -0,0 +1,39 @@ +{% extends "maposmatic/base.html" %} + +{% comment %} + coding: utf-8 + + maposmatic, the web front-end of the MapOSMatic city map generation system + Copyright (C) 2012 David Decotigny + Copyright (C) 2012 Frédéric Lehobey + Copyright (C) 2012 Pierre Mauduit + Copyright (C) 2012 David Mentré + Copyright (C) 2012 Maxime Petazzoni + Copyright (C) 2012 Thomas Petazzoni + Copyright (C) 2012 Gaël Utard + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU Affero General Public License as + published by the Free Software Foundation, either version 3 of the + License, or any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU Affero General Public License for more details. + + You should have received a copy of the GNU Affero General Public License + along with this program. If not, see . +{% endcomment %} +{% load i18n %} +{% load extratags %} + +{% block body-class %}about{% endblock %} +{% block menu-about %}active{% endblock %} + +{% block title %}{% trans "User Guide" %}{% endblock %} +{% block page %} + +{% include "user-guide.html" %} + +{% endblock %}