src/libgpx/gpx.php

   1 <?php
   2 /**
   3  * gpx.php
   4  *
   5  * Copyright 2018 Andy Street <andy@street.me.uk>
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 2 of the License, or
  10  * (at your option) any later version.
  11  *
  12  * This program is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with this program; if not, write to the Free Software
  19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  20  * MA 02110-1301, USA.
  21  *
  22  *
  23  */
  24
  25 namespace libgpx;
  26
  27 use \DateTimeInterface;
  28
  29 /**
  30  * A GPX file.
  31  *
  32  * @see https://www.topografix.com/gpx.asp
  33  *
  34  * @author Andy Street <andy@street.me.uk>
  35  */
  36 class GPX implements Geographic
  37 {
  38
  39   /**
  40    * The program that created the GPX file.
  41    *
  42    * @var string
  43    */
  44   protected $creator;
  45
  46   /**
  47    * The name of the GPX file.
  48    *
  49    * @var string
  50    */
  51   protected $name;
  52
  53   /**
  54    * A description of the contents of the GPX file.
  55    *
  56    * @var string
  57    */
  58   protected $desc;
  59
  60   /**
  61    * The person or organization who created the GPX file.
  62    *
  63    * @var Person
  64    */
  65   protected $author;
  66
  67   /**
  68    * Copyright and license information governing use of the file.
  69    *
  70    * @var Copyright
  71    */
  72   protected $copyright;
  73
  74   /**
  75    * Links to other resources that describe this GPX file.
  76    *
  77    * @var TypedDoublyLinkedList (Link)
  78    */
  79   protected $links;
  80
  81   /**
  82    * The creation time of the file.
  83    *
  84    * @var DateTimeInterface
  85    */
  86   protected $time;
  87
  88   /**
  89    * A list of keywords classifying this GPX file.
  90    *
  91    * @var TypedDoublyLinkedList (string)
  92    */
  93   protected $keywords;
  94
  95   /**
  96    * A list of XML snippets describing unsupported metadata.
  97    *
  98    * @var TypedDoublyLinkedList (string)
  99    */
 100   protected $metadataExtensions;
 101
 102   /**
 103    * A list of waypoints.
 104    *
 105    * @var TypedDoublyLinkedList (Point)
 106    */
 107   protected $waypoints;
 108
 109   /**
 110    * A list of routes.
 111    *
 112    * @var TypedDoublyLinkedList (Route)
 113    */
 114   protected $routes;
 115
 116   /**
 117    * A list of tracks.
 118    *
 119    * @var TypedDoublyLinkedList (Track)
 120    */
 121   protected $tracks;
 122
 123   /**
 124    * Fetch the name of the program that created the GPX file.
 125    *
 126    * @return string|null The creator or null if not set.
 127    */
 128   public function getCreator()
 129   {
 130     return $this->creator;
 131   }
 132
 133   /**
 134    * Set the name of the program that created the GPX file.
 135    *
 136    * @param string|null $creator The program name or null to delete.
 137    * @return void
 138    */
 139   public function setCreator(string $creator = null)
 140   {
 141     $this->creator = $creator;
 142   }
 143
 144   /**
 145    * Fetch the file name.
 146    *
 147    * @return string|null The name or null if not set.
 148    */
 149   public function getName()
 150   {
 151     return $this->name;
 152   }
 153
 154   /**
 155    * Set the name of the file.
 156    *
 157    * @param string|null $name The file name or null to delete.
 158    * @return void
 159    */
 160   public function setName(string $name = null)
 161   {
 162     $this->name = $name;
 163   }
 164
 165   /**
 166    * Fetch the description of the file.
 167    *
 168    * @return string|null The description or null if not set.
 169    */
 170   public function getDesc()
 171   {
 172     return $this->desc;
 173   }
 174
 175   /**
 176    * Set the description of the file.
 177    *
 178    * @param string|null $desc The description or null to delete.
 179    * @return void
 180    */
 181   public function setDesc(string $desc = null)
 182   {
 183     $this->desc = $desc;
 184   }
 185
 186   /**
 187    * Fetch the author of the file.
 188    *
 189    * @return Person|null The author or null if not set.
 190    */
 191   public function getAuthor()
 192   {
 193     return $this->author;
 194   }
 195
 196   /**
 197    * Set the author of the file.
 198    *
 199    * @param Person|null $author The author or null to delete.
 200    * @return void
 201    */
 202   public function setAuthor(Person $author = null)
 203   {
 204     $this->author = $author;
 205   }
 206
 207   /**
 208    * Fetch the copyright details for the file.
 209    *
 210    * @return Copyright|null The copyright or null if not set.
 211    */
 212   public function getCopyright()
 213   {
 214     return $this->copyright;
 215   }
 216
 217   /**
 218    * Set the copyright details for the file.
 219    *
 220    * @param Copyright|null $copyright The copyright detail or null to delete.
 221    * @return void
 222    */
 223   public function setCopyright(Copyright $copyright = null)
 224   {
 225     $this->copyright = $copyright;
 226   }
 227
 228   /**
 229    * Fetch links to other resources.
 230    *
 231    * @param boolean $create Create the list if it does not already exist.
 232    * @return TypedDoublyLinkedList
 233    */
 234   public function getLinks(bool $create = true)
 235   {
 236     if ($create && $this->links === null)
 237       $this->links = new TypedDoublyLinkedList('libgpx\Link');
 238     return $this->links;
 239   }
 240
 241   /**
 242    * Fetch the time the GPX file was created.
 243    *
 244    * @return DateTimeInterface|null A timestamp or null if not set.
 245    */
 246   public function getTime()
 247   {
 248     return $this->time;
 249   }
 250
 251   /**
 252    * Set the time at which the file was created.
 253    *
 254    * @param DateTimeInterface $time The creation time or null to delete.
 255    */
 256   public function setTime(DateTimeInterface $time = null)
 257   {
 258     $this->time = $time;
 259   }
 260
 261   /**
 262    * Fetch a list of keywords for this GPX file.
 263    *
 264    * @param boolean $create Create the list if it does not already exist.
 265    * @return TypedDoublyLinkedList The keywords
 266    */
 267   public function getKeywords(bool $create = true)
 268   {
 269     if ($create && $this->keywords === null)
 270       $this->keywords = new TypedDoublyLinkedList('string');
 271     return $this->keywords;
 272   }
 273
 274   /**
 275    * Fetch a list of XML snippets describing unsupported metadata.
 276    *
 277    * @param boolean $create Create the list if it does not already exist.
 278    * @return TypedDoublyLinkedList The keywords
 279    */
 280   public function getMetadataExtensions(bool $create = true)
 281   {
 282     if ($create && $this->metadataExtensions === null)
 283         $this->metadataExtensions = new TypedDoublyLinkedList('string');
 284     return $this->metadataExtensions;
 285   }
 286
 287   /**
 288    * Fetch a list of waypoints.
 289    *
 290    * @param boolean $create Create the list if it does not already exist.
 291    * @return TypedDoublyLinkedList A list of waypoints.
 292    */
 293   public function getWaypoints(bool $create = true)
 294   {
 295     if ($create && $this->waypoints === null)
 296       $this->waypoints = new TypedDoublyLinkedList('libgpx\Point');
 297     return $this->waypoints;
 298   }
 299
 300   /**
 301    * Fetch a list of routes.
 302    *
 303    * @param boolean $create Create the list if it does not already exist.
 304    * @return TypedDoublyLinkedList A list of routes.
 305    */
 306   public function getRoutes(bool $create = true)
 307   {
 308     if ($create && $this->routes === null)
 309       $this->routes = new TypedDoublyLinkedList('libgpx\Route');
 310     return $this->routes;
 311   }
 312
 313   /**
 314    * Fetch a list of tracks.
 315    *
 316    * @param boolean $create Create the list if it does not already exist.
 317    * @return TypedDoublyLinkedList A list of tracks.
 318    */
 319   public function getTracks(bool $create = true)
 320   {
 321     if ($create && $this->tracks === null)
 322       $this->tracks = new TypedDoublyLinkedList('libgpx\Track');
 323     return $this->tracks;
 324   }
 325
 326   /**
 327    * Fetch a bounding box that covers the feature.
 328    *
 329    * @return Bounds|null A bounding box covering the extent of the feature or
 330    *         null if not applicable.
 331    */
 332   public function getBounds()
 333   {
 334     $result = null;
 335     $lists = [
 336       $this->waypoints,
 337       $this->routes,
 338       $this->tracks
 339     ];
 340     foreach ($lists as $list) {
 341       if ($list === null) continue;
 342       foreach ($list as $geo) {
 343         $bounds = $geo->getBounds();
 344         if ($bounds === null) continue;
 345         $result = ($result === null ? $bounds : $result->extend($bounds));
 346       }
 347     }
 348     return $result;
 349   }
 350
 351 }