This RubyGem provides an application and a library to document nature activities.

Installation

  1. Install the Prerequisites

  2. Install the gem

    Note
    		 Use sudo on Ubuntu 
    gem install natour

Prerequisites

Install the required components by following the instructions below. Please read the installation guide of the components if you encounter any problems or if your OS is not listed below (e. g. macOS).

Windows

  1. Download and install the latest version from RubyInstaller for Windows

  2. Download and install the latest version from Google Chrome-Webbroser

  3. Add BROWSER_PATH=path\to\chrome.exe to the environment variables

  4. Log off Windows and back on again to ensure the environment variable takes effect

Ubuntu

  1. Install Ruby

    sudo apt install ruby

  2. Install Nokogiri dependencies

    sudo apt install build-essential patch ruby-dev zlib1g-dev liblzma-dev

  3. Install libvips

    sudo apt install libvips

  4. Install Google Chrome-Webbroser

    wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo apt install ./google-chrome-stable_current_amd64.deb

Application

Create reports in AsciiDoc format from a directory with GPS tracks, images and species lists. After editing the AsciiDoc files (e.g. selecting the images and describing the adventure), they can be converted to various formats, including PDF and HTML. A typical directory structure and the necessary commands are shown in the following example.

└─ 2022-02-26 Monte Caslano             < Root directory
   ├─ Bilder                            < Directory containing images
   │  ├─ IMG_7687.JPG
   │  ├─ IMG_7688.JPG
   │  ├─ ...
   │  └─ IMG_7870.JPG
   ├─ 2022-02-26 14.45.27.fit           < GPS track exported by GPS device
   ├─ 2022-02-26 14.45.27.gpx           < GPS track exported by GPS device
   ├─ 2022-02-26 14.45.27.jpg           < Image of the map section created
   ├─ 2022-02-26 Monte Caslano.adoc     < Report in AsciiDoc format created
   ├─ 2022-02-26 Monte Caslano.pdf      < Report converted from AsciiDoc to PDF
   ├─ 2022-02-26MonteCaslano.csv        < Species list exported from Kosmos Vogelführer
   └─ flora_helvetica_sammlungen.csv    < Species list exported from Flora Helvetica
natour report create "2022-02-26 Monte Caslano"
natour report convert "2022-02-26 Monte Caslano/2022-02-26 Monte Caslano.adoc"
Note
 Use natour --help to get more information.

Configuration

The configuration is built by loading YAML files in hierarchical order. The files must be named .natour.yml and are loaded first from the home directory of the current user and then from the current working directory. The values of the previously loaded files are overwritten by the values of the files loaded later. The values are stored internally in nested, dictionary-like collections (Ruby Hash), where the structure follows to the command line interface. All keys are of type Ruby Symbol and correspond to the commands and options, with middle hyphens replaced by underscores, leading hyphens removed, and without the no- prefix for boolean switches. The following configuration file shows all entries and their default values.

---
:report:
  :create:
    :out_dir: null
    :out_file: null
    :overwrite: false
    :track_formats:
      - :gpx
      - :fit
    :map: true
    :map_layers: []
    :adoc_author: null
    :short_species_names: false
  :convert:
    :out_dir: null
    :out_file: null
    :overwrite: false
    :backend: :pdf
    :draft: false
    :draft_backend: null
    :image_maxdim: 1800
:map:
  :create:
    :out_dir: null
    :out_file: null
    :overwrite: false
    :gps_colors: []
    :map_layers: []
    :image_size: [1200, 900]

How to restrict GPS tracks to the FIT format (see FIT SDK) and add additional map layers (see API FAQ - GeoAdmin API 3.0 documentation) is shown in the example below.

---
:report:
  :create:
    :track_formats:
      - :fit
    :map_layers:
      - ch.swisstopo.swisstlm3d-wanderwege
      - ch.bav.haltestellen-oev

Library

The basic use is shown in the following example. For details, see the source code and the unit tests.

require 'natour'

Natour::create_reports('path/to/dir')
require 'natour'

Natour::convert_report('path/to/dir/report.adoc')

Testing

Execute the following command to run the tests. Add -Ilib to the command to run the tests against the library sources instead of the installed gem.

Note
 Some tests require an Internet connection. 
ruby ./test/test.rb

Run the following command to check the style and formatting by RuboCop.

rubocop