schema_version: 7.0
type: filter
identifier: gpstext
title: GPS Text
version: 2
copyright: Meltytech, LLC
creator: Daniel F
license: LGPLv2.1
language: en
tags:
  - Video
description: Overlay GPS-related text onto the video
notes: >
  The GPS text filter will search for keywords in the text to be overlaid
  and will replace those keywords on a frame-by-frame basis. 
  It is based on dynamictext filter.

parameters:
  - identifier: argument
    argument: yes
    title: GPS text
    type: string
    description: |
      The text to overlay. May include keywords enclosed in "#".
      Keywords include:
        * #gps_lat#           - the GPS latitude value
        * #gps_lon#           - the GPS longitude value
        * #gps_elev#          - the GPS altitude value
        * #gps_speed#         - GPS speed 
        * #gps_dist#          - total distance so far 
        * #gps_datetime_now#  - date and time of current gps point shown
        * #file_datetime_now# - date and time of current frame in video file
        * #hr#                - heart rate (if present in gps file)
        * #gps_bearing#       - current GPS bearing (degrees 0-360)
        * #gps_compass#       - current GPS direction (8 divisions: N, NE, E, etc)
        * #gps_vdist_up#      - total GPS altitude gain so far
        * #gps_vdist_down#    - total GPS altitude loss so far
        * #gps_dist_uphill#   - total distance travelled uphill so far
        * #gps_dist_downhill# - total distance travelled downhill so far
        * #gps_dist_flat#     - total distance travelled on flat area so far
      An extra word "RAW" (uppercase!) can be added to the keyword to display the 
      unchanged value from the file. If a keyword can't produce valid data it will 
      print "--".
      Time-based keywords can include a strftime format string to customize the
      output and a number (representing seconds) preceeded by '+' or '-' which will 
      offset the actual time. For example,  "#gps_datetime_now %I:%M:%S %p +3600#" shows 
      only the time in 12-hour format, offset by 1 hour.
      Speed and distance keywords may include an extra format keyword to convert 
      the value to metric/imperial units. Default is meters and km/h respectively.
      Supported formats, distance: m|meter, km|kilometer*, mi|mile*, ft|feet, nm|nautical*;
      speed: ms|m/s|meter, km|km/h|kilo, mi|mi/h|mile, ft|ft/s|feet, kn|nm/h|knots.
      Computed values are calculated since begining of GPS file or since 
      "gps_processing_start_time" property, if set.
      The # may be escaped with "\".
    required: yes
    readonly: no
    default: >
      Speed: #gps_speed#km/h\n
      Distance: #gps_dist#m\n
      Altitude: #gps_elev#m\n\n
      GPS time: #gps_datetime_now#\n
      GPS location: #gps_lat#, #gps_lon#
    widget: text
    
  - identifier: resource
    title: GPS File/URL
    description: >
      "The fullpath of file containing location (GPS) data. Supported extensions: .gpx, .tcx."
    type: string
    required: yes
    readonly: no
    widget: fileopen
    
  - identifier: time_offset
    title: Time offset
    type: integer
    description: >
      An offset (in seconds) to be added to the video file to match it to the GPS track.
      Most of the time this will at least need to be set to the timezone difference 
      between the 2 files plus some seconds if the video recording device isn't 
      precisely set to correct time. GPS time is always exact and in UTC. 
      Use positive values if GPS is ahead of video and negative otherwise.
    default: 0
    readonly: no
    required: no
    mutable: yes
    widget: text
    
  - identifier: smoothing_value
    title: Smoothing level
    type: integer
    description: >
      How many GPS points to smooth in order to eliminate GPS errors.
      A value of 0 only exposes the raw values from file.
      A value of 1 does not smooth locations, it only calculates the extra 
      fields (speed, distance, etc) it also interpolates missing values for
      heart rate and altitude. 
    default: 5
    minimum: 0
    readonly: no
    required: no
    mutable: yes
    widget: text
    
  - identifier: gps_processing_start_time
    title: GPS processing start time
    type: string
    description: >
      A UTC date and time (formatted as "yyyy-MM-dd hh:mm:ss") from which to start
      processing the gps file. Use if the GPS file has extra points before the video
      and you want to ignore them (can be used to track the distance since begining 
      of a segment).
      If the string provided doesn't perfectly match the format, it will be ignored.
    default: "yyyy-MM-dd hh:mm:ss"
    readonly: no
    required: no
    mutable: yes
    widget: text
    
  - identifier: speed_multiplier
    title: Speed multiplier
    type: float
    description: >
      If the video file is a timelapse (or slow motion), use this value to set the
      speed up/slow down ratio. 
      Sample values: 30 for 30x timelapse, 0.25 for 4x slow motion footage. 
    default: 1
    readonly: no
    required: no
    mutable: yes
    widget: text
    
  - identifier: updates_per_second
    title: Updates per second
    type: float
    description: >
      Controls how many times per second is the GPS text updated on video (interpolated).
      A value of 0 will only update text when a real gps point has been recorded.
      Can be used in combination with speed_multiplier.
    default: 1
    readonly: no
    required: no
    mutable: yes
    widget: text

    # READ ONLY:
  - identifier: gps_start_text
    title: GPS start time
    description: Date and time of the first valid GPS point.
    readonly: yes
    
  - identifier: video_start_text
    title: Video start time
    description: Date and time of the video file.
    readonly: yes
    
  - identifier: auto_gps_offset_start
    title: Auto offset start
    description: > 
      Provides a helper offset to guarantee start of video file syncs with the start of gps file.
      Correctly sets the offset if video file and gps recording was started at the same time.
    readonly: yes
    
  - identifier: auto_gps_offset_now
    title: Auto offset now
    description: > 
      Provides a helper offset to sync the first gps point to current video time (it is 
      updated every second).
      Correctly sets the offset if you video record the moment gps starts.
    readonly: yes
    
  - identifier: auto_gps_processing_start_now
    title: Auto gps processing start now
    description: > 
      Provides a helper offset to sync the gps_processing_start_time property to current 
      video time (it is updated every second). DateTime string.
    readonly: yes

  - identifier: geometry
    title: Geometry
    type: rect
    description: A set of X/Y coordinates by which to adjust the text.
    default: 10%/10%:80%x80%:100%
    
  - identifier: family
    title: Font family
    type: string
    description: >
      The typeface of the font.
    default: Sans
    readonly: no
    mutable: yes
    widget: combo

  - identifier: size
    title: Font size
    type: integer
    description: >
      The size in pixels of the font.
    default: 26
    readonly: no
    mutable: yes
    widget: spinner

  - identifier: style
    title: Font style
    type: string
    description: >
      The style of the font.
    values:
      - normal
      - italic
    default: normal
    readonly: no
    mutable: yes
    widget: combo

  - identifier: weight
    title: Font weight
    type: integer
    description: The weight of the font.
    minimum: 100
    maximum: 1000
    default: 400
    readonly: no
    mutable: yes
    widget: spinner

  - identifier: fgcolour
    title: Foreground color
    type: string
    description: >
      A color value is a hexadecimal representation of RGB plus alpha channel
      as 0xrrggbbaa. Colors can also be the words: white, black, red, green,
      or blue. You can also use a HTML-style color values #rrggbb or #aarrggbb.
    default: 0xffffffff
    readonly: no
    mutable: yes
    widget: color

  - identifier: bgcolour
    title: Background color
    type: string
    description: >
      A color value is a hexadecimal representation of RGB plus alpha channel
      as 0xrrggbbaa. Colors can also be the words: white, black, red, green,
      or blue. You can also use a HTML-style color values #rrggbb or #aarrggbb.
    default: 0x00000000
    readonly: no
    mutable: yes
    widget: color

  - identifier: olcolour
    title: Outline color
    type: string
    description: >
      A color value is a hexadecimal representation of RGB plus alpha channel
      as 0xrrggbbaa. Colors can also be the words: white, black, red, green,
      or blue. You can also use a HTML-style color values #rrggbb or #aarrggbb.
    readonly: no
    mutable: yes
    widget: color

  - identifier: outline
    title: Outline Width
    type: string
    description: >
      The width of the outline in pixels.
    readonly: no
    default: 0
    minimum: 0
    maximum: 3
    mutable: yes
    widget: spinner

  - identifier: pad
    title: Padding
    type: integer
    description: >
      The number of pixels to pad the background rectangle beyond edges of text.
    readonly: no
    default: 0
    mutable: yes
    widget: spinner

  - identifier: halign
    title: Horizontal alignment
    description: >
      Set the horizontal alignment within the geometry rectangle.
    type: string
    default: left
    values:
      - left
      - centre
      - right
    mutable: yes
    widget: combo

  - identifier: valign
    title: Vertical alignment
    description: >
      Set the vertical alignment within the geometry rectangle.
    type: string
    default: bottom
    values:
      - top
      - middle
      - bottom
    mutable: yes
    widget: combo