(:groupheader:)>>rfloat<< (:if enabled NZTopo:) %rfloat smaller%{$NZTopoVersion}%% (:nztopo kml="https://kiwiwiki.nz/testdata/2014-05-30 13_54_13.kml" height=300:) (:else:) %newwin%[[https://www.topomap.co.nz/NZTopoMap?v=2&kml="http%3A%2F%2Fkiwiwiki.nz%2Ftestdata%252F2014-05-30%252013_54_13.kml"&new=1|Attach:NZTopoexample.png]] (:ifend:) >>recipeinfo<< Summary: Use %newwin%[[https://www.topomap.co.nz/]] to display an excerpt from a New Zealand topographic map in a PmWiki website Version: 2022-02-22 Prerequisites: PmWiki 2.3.2 and PHP 7.4 or newer Status: Production Maintainer: [[~skiwi]] Licence: [[https://www.gnu.org/licenses/gpl-3.0.en.html | GPL3]]'^[[https://www.gnu.org/licenses/quick-guide-gplv3.en.html|#]]^' File: Attach:{$:Version}-nztopo.php.txt Categories: [[!Markup]] [[!Images]] [[!Includes]] [[!PHP74]] [[!Maps]] Users: {$Users} ([[{$FullName}-Users|view]] / [[{$FullName}-Users?action=edit|edit]]) Discussion: [[{$Name}-Talk]] >><< !! Questions answered by this recipe <:vspace> How do I display on a PmWiki page part of a topographic map of New Zealand using the official %newwin%[[https://www.linz.govt.nz/|LINZ]]'s 1:50,000 / [[https://www.linz.govt.nz/land/maps/topographic-maps/topo50-maps|Topo50]] and 1:250,000 / [[https://www.linz.govt.nz/land/maps/topographic-maps/topo250-maps|Topo250]] maps, as well as 1:25,000 / Topo25 maps for some of the [[https://www.linz.govt.nz/land/maps/topographic-maps/new-zealand-offshore-islands-maps|offshore islands]]? <:vspace> [[#desc]] !! Description (:Description This recipe generates the markup for %newwin%[[https://www.topomap.co.nz/#info | topomap.co.nz]]'s ability to share and embed the topo map:) {$Description} <:vspace> !!! Simple use cases You can use [[Cookbook:Ape#nz | Ape: Automagical PmWiki Embed]] to embed a map frame from [[https://www.topomap.co.nz/ | NZ Topo Map]], and embed GPX or KML traces. <:vspace> To embed a map frame from NZTopoMap, find thelocation on the [[https://www.topomap.co.nz/ | website]], click on "Share Map", in the sidebar near the top click on the button after "Copy link to share map". * Place this link in the page, and wrap it with %pmhlt%[@%embed%...%%@] or [@%map%...%%@] wikistyle: * %pmhlt%@@[=%map height=400px% [[ https://www.topomap.co.nz/NZTopoMap?v=2&ll=-41.315866,174.811448&z=15 | my map]] %%=]@@ <:vspace> If the link URL contains "&pin=1" but not "&lbl=", then link text will become the label of the pin. <:vspace> To embed GPX or KML tracks, attach them to the page with [@[[Attach:sample.gpx]]@] or otherwise link to them, then wrap them in the wikistyles "map nztopo": * %pmhlt%[@%map nztopo% Attach:[=trace route.kml=] %%@] <:vspace> [[#install]] !! Installation * download @@Attach:{$:Version}-nztopo.php@@ * copy to the @@/cookbook/@@ directory as @@nztopo.php@@ * add to @@config.php@@ the line --< %pmhlt%[@include_once("$FarmD/cookbook/nztopo.php");@] * optionally add CSS styles to @@local.css@@ <:vspace> [[#usage]] !! Usage Place the directive, as described below, in your PmWiki page. <:vspace> You can specify a locale as a decimal WGS84 latitude and longitude (@@ll@@), in %newwin%[[Attach:nztm.pdf | NZTM]] coordinates (@@nzne@@), as a Topo50 map reference (@@mapref@@), or specify a publicly accessible the URL of a gpx or kml file to overlay on the map (@@kml, gmx@@). <:vspace> The scale of the map, but not the image, will automatically resize to the area covered by the kml / gpx data, or you can optionally specify the map zoom factor and the image size (height and width) to control the area of the map shown. <:vspace> You can specify bounds of an area, by latitude and longitude (@@llbs@@), or NZTM coordinates (@@nzbs@@). The recipe will resize the map image based on the size of the rectangle defined by the bounds and the zoom scale factor. <:vspace> You can optionally specify to show a pin marker (@@pin@@), and again optionally show a tool tip label for the marker (@@label@@). <:vspace> The recipe provides a page variable [@{$NZTopoVersion}@] which contains the current version, and [@$NZTopo@] for a [@(:if enabled NZTopo:)@] recipe installation check. <:vspace> <:vspace> [[#config]] !! Configuration To select the map area: %pmhlt%@@[=(:=]nztopo '''ll'''=''latitude,longitude'' @@ -> @@'''llbs'''=''latitude,longitude;latitude,longitude[;latitude,longitude...]'' @@ -> @@'''nzne'''=''northing,easting'' @@ -> @@'''nzbs'''=''northing,easting;northing,easting[;northing,easting...]'' @@ -> @@'''mapref'''=''mapref''@@ To specify a route, url must be quoted: -> @@'''kml'''="''url''" '''gpx'''="''url''" @@ -> @@'''height'''=''pixels'' '''width'''=''pixels'' '''pin'''=''1'' '''label'''="''string''" '''zoom'''=''number'' '''float'''=''left|right'' '''clear'''=''both|right|left'':) @@ <:vspace> * @@ll= @@-- centre point of the map as a decimal latitude,longitude * @@llbs= @@-- decimal latitude longitude bounds: latitude,longitude;latitude,longitude[;latitude,longitude...] * @@nzne= @@-- centre point of the map as an %newwin%[[https://www.linz.govt.nz/data/geodetic-system/datums-projections-and-heights/projections/new-zealand-transverse-mercator-2000|NZTM]] northing,easting * @@nzbs= @@-- NZTM bounds: northing,easting;northing,easting[;northing,easting...] * @@mapref= @@-- NZ Topo50 grid reference, @@AAxxxyyy@@, e.g. %newwin%[[https://www.topomap.co.nz/NZTopoMap?v=2&z=14&pin=1&mapref=BN33991890 | @@BN33991890@@]] Only one of: ll; llbs; nzne; nzbs; mapref; can be specified. <:vspace> * @@kml= @@-- URL to %newwin%[[https://developers.google.com/kml/documentation/|kml]]/[[Wikipedia:GeoRSS|GeoRSS]] file, or * @@kml= @@-- wiki filename * @@gpx= @@-- URL to %newwin%[[http://www.topografix.com/gpx_for_users.asp|gpx]] file, or * @@gpx= @@--wiki filename Only one of: kml; gpx; can be specified <:vspace> * @@height= @@-- image height in pixels, default is 150 * @@width= @@-- image width in pixels, default is 300 * @@float= @@-- float image to left or right * @@clear= @@-- clear image to left, right, or both * @@raw= @@-- raw=1 for %newwin%[[https://www.dropbox.com/en/help/201 | DropBox files]] <:vspace> * @@pin= @@-- show pin (1) * @@label= @@-- tool tip label for pin * @@zoom= @@-- scale factor for map (5 to 15), zoom is ignored when bounds parameters are supplied * @@caption= @@-- text string caption for map <:vspace> !!! @@config.php@@ settings You can change the default zoom factor by using the variable [@$NZTopoZoom@] in @@config.php@@. For example ->%pmhlt%[@$NZTopoZoom = 10; # set default zoom factor for NZTopo directive @] By default clicking on the maps opens a full screen map in a new browser tab. You can change this as follows ->%pmhlt%[@$NZTopoNewwin = 0; # set open in new window flag for NZTopo directive @] <:vspace> !!! CSS You can add CSS similar to this to @@local.css@@. ->%hlt css%[@/* CSS for NZTopo recipe */ .nztopo { margin: 0.5rem; } .nztopoframe { border-radius: 0.5rem; }@] <:vspace> [[#notes]] !! Notes For the bounds @@llbs@@ and @@nzbs@@ parameters only two coordinates need to be supplied, but they take any number of coordinates. If a user had a bunch of coordinates they're interested in they don't need to manually calculate the two corner points to pass in themselves. Passing in all of them and allows the map work out what the bounding box is, e.g. they might have 10 waypoints from a tramp - they can just pass all 10 coordinates in and the map will adjust its bounds to make sure all 10 waypoint coordinates are visible. <:vspace> Zoom 5 to 12 show the Topo250 map series and zoom 13 to 15 show the Topo50. <:vspace> The API for specifying a gpx file differs from that for specifying a kml file. See the recipe's code for the extra handling required to use the API with a kml file. <:vspace> Use a recipe version earlier than 2022-01-07 for PHP versions earlier than PHP 7. <:vspace> !! Web server For this recipe to work your web server must be able to serve @@gpx@@ and @@kml@@ files. You will need to add the [[https://www.iana.org/assignments/media-types/media-types.xhtml|media types]] * kml = @@application/vnd.google-earth.kml+xml@@'^[[application/vnd.google-earth.kml+xml|#]]^' * gpx = @@application/gpx+xml@@'^[[Wikipedia:GPS_Exchange_Format|#]]^' <:vspace> [[#relnotes]] !! Change log / Release notes >>pre<< 2022-02-22 can attach wiki files (thanks Petko), strings must be quoted 2022-01-15 filename can now be a PmWiki page name, revise quoted string regex 2022-01-07 strict_types=1, use type hints, use <figure>, implement caption 2021-06-18 Fix incorrect placement of "-" in regex for PHP 7.4; 2021-04-21 Caption, inline-block 2018-07-10 Don't generate zoom parameter when llbs or nzbs 2018-05-14 Call topomap with https 2018-05-12 Make PHP 7.2 compatible 2015-07-01 gpx and kml now work, improve code, production ready 2014-08-09 Make PHP 5.5 compatible >><< <:vspace> [[#seealso]] !! See also <:vspace> * %newwin%[[https://www.topomap.co.nz/ | NZ Topo Map]] * %newwin%[[https://kiwiwiki.nz/pmwiki/pmwiki.php/Cookbook/NZTopo | NZTopo home]] ** %newwin%[[https://kiwiwiki.nz/pmwiki/pmwiki.php/Test/NZTopo-Zoom | test NZTopo zoom]] ** %newwin%[[https://kiwiwiki.nz/pmwiki/pmwiki.php/Test/NZTopo-Attach | test NZTopo kml and gpx]] * %newwin%[[https://kiwiwiki.nz/pmwiki/pmwiki.php/Cookbook/NZTopoAPI | NZTopo API]] <:vspace> [[#contributors]] !! Contributors * special thanks to %newwin%[[https://www.gavinharriss.com/ | Gavin Harriss]] for %newwin%[[https://www.topomap.co.nz/ | NZ Topo Map]] * special thanks to Petko for the [[PmWiki:Functions#DownloadUrl | DownloadUrl function]] <:vspace> [[#comments]] !! Comments See discussion at [[{$Name}-Talk]] <:vspace> [[#faq]] >>faq display=none<< <:vspace> Q: A:(:groupfooter:) <:block>