Tutorial

The tutorial is not much of a tutorial, but rather to example files with results.

Static Map

The first and maybe most important result is the static map, which can be plotted using the following example (link to download script at the bottom.)

import sys
import os
import glob

# Add module path
sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

from merplot.mermaid_plot import MermaidLocations
from merplot.mermaid_plot import get_coordinates_from_kml_path

# Add data path
data_path = os.path.join(os.path.dirname(
        os.path.dirname(os.path.abspath(__file__))), "data")
sys.path.append(data_path)

# File list
file_list = glob.glob(os.path.join(data_path, "*.vit"))

# WMS setup: Set to true of you have internet and want a high res map
wms = True
wms_url = 'https://ahocevar.com/geoserver/wms'
wms_layer = 'ne:NE1_HR_LC_SR_W_DR'

# Filter file
filter_file = os.path.join(data_path, "mermaid_filter.yml")

# Run
ML = MermaidLocations.from_vit_file(file_list,
                                filter_dict=filter_file,
                                minlat=-45,
                                legend_cols=1, legend_title="SPPIM",
                                trajectory_width=6,
                                wms=wms, wms_url=wms_url,
                                wms_layer=wms_layer,
                                figsize=(30, 8), fontsize=14)

# Get paths to auxiliary data
pp_path = os.path.join(data_path, "Papeete-Papeete.kml")
pn_path = os.path.join(data_path, "Papeete-Noumea.kml")
np_path = os.path.join(data_path, "Noumea-Papeete.kml")

# Get tracks from kml paths
pp_lat, pp_lon = get_coordinates_from_kml_path(pp_path)
pn_lat, pn_lon = get_coordinates_from_kml_path(pn_path)
np_lat, np_lon = get_coordinates_from_kml_path(np_path)

# Add ship paths
ML.add_aux_data(np_lon, np_lat, color="y", linewidth=2.5,
                label="Nouméa-Pape'ete - Jun/Jul '18")
ML.add_aux_data(pp_lon, pp_lat, color="r", linewidth=2.5,
                label="Pape'ete-Pape'ete - Aug '18")
ML.add_aux_data(pn_lon, pn_lat, color="g", linewidth=2.5,
                label="Pape'ete-Nouméa - Aug '19")

# Pape'ete
p_lon = -149.5585
p_lat = -17.5516

# Nouméa
n_lon = 166.4416
n_lat = -22.2711

# Shimizu
s_lon = 138.50
s_lat = 35.00

# Valparaíso
v_lon = -71.63
v_lat = -33.37

# Add Noumea marker
ML.add_aux_data(p_lon, p_lat, linestyle="None", marker="o", markersize=7,
            markeredgecolor='k', markerfacecolor='r', zorder=200)
# Add Papeete marker
ML.add_aux_data(n_lon, n_lat, linestyle="None", marker="o", markersize=7,
            markeredgecolor='k', markerfacecolor='r', zorder=200)
# Shimizu marker
ML.add_aux_data(s_lon, s_lat, linestyle="None", marker="o", markersize=7,
            markeredgecolor='k', markerfacecolor='r', zorder=200)
# Valparaíso marker
ML.add_aux_data(v_lon, v_lat, linestyle="None", marker="o", markersize=7,
            markeredgecolor='k', markerfacecolor='r', zorder=200)

# Shimizu - Valparaíso Dec ’18 - Jan ‘19 ship track
ML.add_aux_data([s_lon, v_lon], [s_lat, v_lat], color="b", linewidth=2.5,
            label="Shimizu-Valparaíso - Dec/Jan ’18/‘19")

# Plot the map
ML.plot()


# To write, use matplotlib options in the plot config.
# **kwargs --> dpi, format, etc.

# Plot
# ML.plot(f=<your_plot_name>, **kwargs)

The results is shown below:

_images/static_mermaid.jpg

this example script

Animation

The other interesting plotting tool is the animation creation tool, which still is based on the same class, but as the name suggests animates the trajectories of the mermaids. It basically works the exact same way, but the plotting of the map is triggered by a different class method.

For the animation and especially to save the movies, certain packages must be installed. If you are working on a Mac:

# Install Imagemagick if you wanna make gifs
brew install imagemagick

# Install ffmpeg if you want to make mpeg's
brew install ffmpeg

Afterwards, you can run the following example.

import sys
import os
import glob

# Add module path
sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))

from merplot.mermaid_plot import MermaidLocations
from merplot.mermaid_plot import get_coordinates_from_kml_path

# Add data path
data_path = os.path.join(os.path.dirname(
        os.path.dirname(os.path.abspath(__file__))), "data")
sys.path.append(data_path)

# File list
file_list = glob.glob(os.path.join(data_path, "*.vit"))

# WMS setup: Set to true of you have internet and want a high res map
wms = True
wms_url = 'https://ahocevar.com/geoserver/wms'
wms_layer = 'ne:NE1_HR_LC_SR_W_DR'

# Filter file
filter_file = os.path.join(data_path, "mermaid_filter.yml")

# Run
ML = MermaidLocations.from_vit_file(file_list,
                                filter_dict=filter_file,
                                minlat=-45,
                                legend_cols=1, legend_title="SPPIM",
                                trajectory_width=6,
                                wms=wms, wms_url=wms_url,
                                wms_layer=wms_layer,
                                figsize=(30, 8), fontsize=14)

# Get paths to auxiliary data
pp_path = os.path.join(data_path, "Papeete-Papeete.kml")
pn_path = os.path.join(data_path, "Papeete-Noumea.kml")
np_path = os.path.join(data_path, "Noumea-Papeete.kml")

# Get tracks from kml paths
pp_lat, pp_lon = get_coordinates_from_kml_path(pp_path)
pn_lat, pn_lon = get_coordinates_from_kml_path(pn_path)
np_lat, np_lon = get_coordinates_from_kml_path(np_path)

# Add ship paths
ML.add_aux_data(np_lon, np_lat, color="y", linewidth=2.5,
                label="Nouméa-Pape'ete - Jun/Jul '18")
ML.add_aux_data(pp_lon, pp_lat, color="r", linewidth=2.5,
                label="Pape'ete-Pape'ete - Aug '18")
ML.add_aux_data(pn_lon, pn_lat, color="g", linewidth=2.5,
                label="Pape'ete-Nouméa - Aug '19")

# Pape'ete
p_lon = -149.5585
p_lat = -17.5516

# Nouméa
n_lon = 166.4416
n_lat = -22.2711

# Shimizu
s_lon = 138.50
s_lat = 35.00

# Valparaíso
v_lon = -71.63
v_lat = -33.37

# Add Noumea marker
ML.add_aux_data(p_lon, p_lat, linestyle="None", marker="o", markersize=7,
            markeredgecolor='k', markerfacecolor='r', zorder=200)
# Add Papeete marker
ML.add_aux_data(n_lon, n_lat, linestyle="None", marker="o", markersize=7,
            markeredgecolor='k', markerfacecolor='r', zorder=200)
# Shimizu marker
ML.add_aux_data(s_lon, s_lat, linestyle="None", marker="o", markersize=7,
            markeredgecolor='k', markerfacecolor='r', zorder=200)
# Valparaíso marker
ML.add_aux_data(v_lon, v_lat, linestyle="None", marker="o", markersize=7,
            markeredgecolor='k', markerfacecolor='r', zorder=200)

# Shimizu - Valparaíso Dec ’18 - Jan ‘19 ship track
ML.add_aux_data([s_lon, v_lon], [s_lat, v_lat], color="b", linewidth=2.5,
            label="Shimizu-Valparaíso - Dec/Jan ’18/‘19")

# Plot the map
ML.plot()


# To write, use matplotlib options in the plot config.
# **kwargs --> dpi, format, etc.

# Plot
# ML.plot(f=<your_plot_name>, **kwargs)

The example output using cartopy’s background map is shown below.

_images/mermaid.mp4

See this example script

Binaries

There are a few binaries that were created to make it easy to plot stuff from the command line. Note that they include loading of files that are in the data directory, such as the deployment routes in .kml format. The above example do the same!

### Simple Map `bash $ ./bin/plot_mermaid_locations.py <.vit files> `

If you use the data from the data directory and are in the merplot directory:

`bash $ ./bin/plot_mermaid_locations.py data/*.vit `

### Animated Map

`bash $ ./bin/animate_trajectories.py <.vit files> `

If you use the data from the data directory and are in the merplot directory:

`bash $ ./bin/animate_trajectories.py data/*.vit `

Happy plotting!