A view is a structure for describing how track data (tracks, vehicles, trackers) should be displayed. You can think of a view as a filter which represents what and how to display the data without changing the underlying data itself. (Axiom, In general we don't mess with raw data and use views as a filter. The exceptions might be demo data. MC)

Views are intended to be defined once and viewed on different applications. For instance a view may be defined using Trackwork, but the same view can be used on SmartTrack (TrackManager), or on a web based track viewer. Views shall not contain any structure that renders it unusable on any of our current platforms (Android, IOS, desktop, or web). (Agreed, MC)

Track views need to have the following properties:

• Portable across multiple platforms (Windows, web, IOS, Android, Java, possibly others)
• Contain little to no data themselves (this assertion is yet to be tested)
  • Reference data objects on the Access server
  • e.g. Tracks, background files
• Require no new server changes, and are represented as a data file
• Allow for track annotation (in addition to what is provided in server now).

Each view can be characterized as:

• A list of tracks
• A project perimeter - Question: Explicit perimeter, reference line from planfile, or both?
• A project wide cycle-line, applying to all tracks unless overridden by a track.
• Annotations applied to the tracks, based upon a time range, supplying a textual note
• The definition of working time for the view
• The project to which view is associated.
• The company to which the project belongs
• The user who created (or updated) the view.
• The date/time and a version of the view.
• UI settings (which may be trivially over-ridden by the user/application as needed).

(Some of these are optional and some are required. Perimeter is optional, the view may be based on time. I can't imaging the list of tracks, project, company, or date/time as optional. Working time (not job hours) is inherently limited by the day assuming we have our terminology straight. There's two elements, the day the tracks occurred and any (optional) job hours. And the day the tracks occurred might be inferred from the tracks? I'll leave the guts to you on what makes sense. MC)

Revision note: 2017-01-13 Previous versions of this page had specified “costCodeList” and “timezone”. These have been moved to the AgtekAccess server's definition of Project. The values are global for a project for all times.

Each view file (X.settings) exists on the “settings” subfolder of the project being used. Any view file named “default.settings” is to be considered the default settings used when no other settings are appropriate. Files named “YYYY-MM-DD.settings” are to be used for that day's tracks. Each day is calculated based on local midnight.

When a view-capable program starts it will first look for the day based settings (if it exists) to be used for the current view settings. If the day based settings are not available (no file), the “default.settings” will be used. If there is no default.settings, the program will revert to using built in default values which are roughly:

• No defined work time
• No defined geofence
• All selected tracks participate in statistics
• All tracks are un-segmented (the entire track day is considered valid)
• No plan view is used
• No cycle lines are available
• Display time zone matches the locale of the computer

The current thinking is to represent a view as a JSON encoded object. This handles the portability and debuggability goals for the views.

• JSON is based upon ASCII, all strings are URL encoded to handle Unicode-16 charcters.
  • All program must URLDecode the strings before display.
• All times are recorded in ISO-8601 format in the Zulu timezone (AKA GMT), but altered for display by the “timezone” setting
• All integer ids (tracks, projects, etc) must be referenced with respect to the company.
  • If a user is not able to authenticate under the same company as specified in the view the application shall not show any data to which it has not access.
  • Data cached in other (non-Access) locations might be shown (application choice).
• planfile is a generic URI, likely to be either ADF or KMZ
  • Access based planfiles use the scheme “access:” + access file path * Locally based planfiles use the scheme “file:” + local path
  • Non ADF or KMZ planfiles are not guaranteed to be portable across applications.
• Tracks (specified by track id, AKA “handle” ) may be
  • A segmented track, specified by the base track id, and a series of segments.
  • Segments are composed of start/end times, and a descriptive text string.
  • Segments times must not exceed the start/end times of the parent track. Start of the first segment, and end of the last segment must also conform to the projects working time. Segments are adjust to fit within the track period and then the working time (if any).
  • Zero or more cycle-lines. For zero cycle lines, do not add the cycle-line field.
• The only currently defined UI components are:
  • cropTracks indicates that a track is cropped by the working time definitions. Non working values are not shown.

 {
    "title": "Example view",
    "companyId": "EX123456",
    "projectId": 137,
    "date": "2016-06-13T10:38:00.000Z",
    "effectiveTime": 1478208875, 
    "version": "1",
    "userId": "joe-designer@example.com",
    "application": "Platform SmartTrack 1.0"
    
    "planfile": "access://Projects/My-Project/Job Files/example-plans.kmz",
    "geofence" : "true", 
    "perimeter": [ [37.1, -121.8, 90], [37.11, -121.81, 90.1]],
    "workTimes: {
                "clipStart": false,
                "morning" : { "start": 28800,
                              "end": 41400 },
                "clipMidday" : true,
                "afternoon" : { "start": 43080,
                                "end": 61200 } ,
                 "clipEnd" : false
                 },
    "tracks": [ { "id": "-1",
                  "cycle-line": [ [37.1, -121.8, 90], [37.11, -121.81, 90.1]],
                  "notes": [ { "time" : 41000. "text": "Decided to order pizza" } ] 
                },
                { "id": "17"
                  "segments": [ 
                      { "start": 28800,
                        "end"  : 41400,
                        "label" : "Clay layer",
                        "calcStats": true },
                      { "start": 43080,
                        "end"  : 61200,
                        "label" : "Sand",
                        "calcStats": false }  ]
                },
                { "id": "18",
                     "visible": false,
                     "segments" : [ { "start": 28800,
                        "end"  : 41400,
                        "label" : "Clay layer" } ],
                      "cycle-line": [ [37.1, -121.8, 90], [37.11, -121.81, 90.1]],
                      "notes" : [ { "time": 41400, "text" : "Pizza arrived" },
                                  { "time": 42000, "text" " "Pizza got cold" } ]
                },
                { "id": "19",
                  "calcStats": false,
                  "label": "The entire track"
                }
               ],
 }
 

The following descriptions are the normative directives for a project view definition. The term “Access” will be used as short hand for the AGTEK Access File and License Server system.

Each View must have, or conform to:

• Each view is a single JSON Object
• required field 'title', which is a string, URLEncoded
• required field 'companyId' corresponding to an Access customer id;
• required field 'projectId' corresponding to an Access project handle
• required field 'date', which will be ISO-8601 format, GMT time zone (Z). This date indicates when the file was saved.
• optional field 'effectiveTime': Unix time value for midnight of the effective day of the view. Required for day specific files, ignored for default.settings.
• required field 'version', for this specification is '1'
• required field 'userId', the Access user id of person creating this instance of the view.
• highly suggested field 'application' indicating version of the generating program, e.g. “Android SmartPlan 1.2.1”
• optional field 'planfile', a URI referring to a file usable for display of plan elements useful for track display.
• optional field 'perimeter', an LLA line describing the job perimeter
• optional field 'worktimes', an object consisting of two work-time segments (morning/afternoon), and booleans indicating if track data should be excluded from non-defined times.
• optional field 'tracks', an array of track-descriptors indicating tracks to display.
• optional field 'geofence', a boolean value indicating if the tracks should be geofenced wrt to the planfile. Lack of the field is equivalent to “false” for geofencing.

Sub-objects:

• tracks, optional, may contain an entry for a series of tracks that may be viewed. If the track id is “-1” the contained data is to be applied to all other tracks unless they supply their own settings. Only supporting cycle-lines and notes right now.
• work-time segments, an object consisting of two fields:
  • required 'start', The number of seconds since the start of the day
  • required 'end', The number of seconds since the start of the day
  • optional 'label', a URL encoded string to be used as a human readable lable of the time segment
• track-descriptor, either an integer id (handle) of the Access track, OR track-object
• track-object, an object consisting of
  • required 'id', an integer value specifying the track Access handle
  • optional 'segments', an array of labeled time segments.
  • optional 'cycle-line', an array of lines specifying cycle lines only for this track.
  • optional 'calcStats', a boolean indicating if this track contributes to statistics. Absence of the attribute is equivalent of “true”.
  • optional 'label', a string value used to be a human readable note about the entire track. Absence of the attribute is equivalent of “”
  • optional, 'visible', a boolean value indicating value of the track's visibility flag. Absence of this attribute is equivalent to “true”.
• segment, a sub object of a track, documenting different sub-track time segments
  • required, 'start', the time that the track segment starts, measured in seconds from the start of the day
  • required, 'end', the time that the track segment ends, measures in seconds from the start of the day
  • optional, 'label', a text description which is used to display segment information
  • optional, 'calcStats', a boolean indicating if this track contributes to statistics. Absence of the attribute is equivalent of “true”.
• notes, a sub-array containing a series of objects. Each object represents a time based note to be shown at playback.
  • required, 'time' seconds since midnight when the note occurred
  • required, 'text' the text of the note.

• Ability to store local copies (potentially altered) of tracks for work purposes
• Bundle local background files and tracks into zip file like ADF or ESZ?