Add point detail in Aven - Team, Comments, Date, etc

[Rob Eavis]

Lots of data is hidden in the .svx file that cannot be access via the (more commonly shared) .3d file. Knowing the team that surveyed a leg or what date exactly that it was done would be invaluable, especially in large projects where the .svx file are not accessible to all. Also being able to add "Comments" for a point, which can then be accessed in Aven would be very useful.

Just thinking how this could work. These features could be interfaced in Aven by clicking (left or right) on a point, bringing up a temporary "information box". The points that include additional comments could maybe be coloured differently to show additional information available.

As this comment would sit with the station, rather than the leg, it could be entered at the [*data passage station left right up down comments] stage, and so exactly specifying which station the comment refers to.

[Eric C. Landgraf]

Walls has a similar functionality, with syntax #Note <station> text about station. I see this mostly used to mark leads, and it is visible-by-default in the 2d lineplot viewer.

I propose we include 2 different data types: *qm <station> "text about lead" (alternately *lead; I think we could make these aliases to each other), and *note <station> "textual comment". I've not dove into the internal representation in the .3d file, but it would be sensible then to "show QMs" and "show notes" in the aven viewer without having to construct a whole tooltip on hover; it would basically just have the text near the station when you zoom in.

A first cut is to add these as keywords in the cavern parser with some syntax semantics documented, as we currently handle *team, *instruments, *ref.

One question that is getting off into the weeds on *qm: do we want a "priority" ranking, so someone can build a little "lead list" app thtat reads the 3d files, and sorts by distance from entrance or point.

[Olly Betts]

Replying to Eric C. Landgraf:

I propose we include 2 different data types: *qm <station> "text about lead" (alternately *lead; I think we could make these aliases to each other)

I think it's better to just stick to one command name (I don't think any existing command has an aliased name), and reading lead can make you think of the metal (i.e. if you pronounce it like "led") so *qm seems the better choice.

A first cut is to add these as keywords in the cavern parser with some syntax semantics documented, as we currently handle *team, *instruments, *ref.

The syntax of *team has been documented for years, and I've just implemented parsing of it (checking the roles therion uses).

I'll look at *instrument (note: no "s") at some point. It also has a documented syntax we could check but at least in CUCC data use is extremely free form, whereas *team mostly used a common syntax (just the opposite way around and with exactly one role; there was also a small but significant amount with was the right way round) so fixing up the CUCC data to work with *team could be almost entirely automated.

*ref is explicitly defined to be opaque to Survex - it's up to the user how they use it. It's defined syntax is effectively that it has no defined syntax, and it doesn't seem helpful to change that.

One question that is getting off into the weeds on *qm: do we want a "priority" ranking, so someone can build a little "lead list" app thtat reads the 3d files, and sorts by distance from entrance or point.

The main problem is I don't think there's really a standard system for QM ranking, though using letters with A being best seems quite common so we could support *qm <grade> <description> and allow OMIT (default: -) for <grade>.

For comments at least, it would be helpful to be able to enter them as part of the data. Either after each station in interleaved style, or in *data passage. Or in non-interleaved data we could have fromcomment and tocomment to allow non-leapfrogged data to be written with the comment for each station with the leg), e.g.:

*data from to tape compass clino tocomment

*comment 1         tip of cairn
1 2 12.34 234 -12  point on wall
2 3 23.45 345 -01  highest point of boulder

Maybe it should be tocommentall if it's going to read the rest of the line (to match ignoreall).

[Eric C. Landgraf]

So, for *qm and possibly *comment, we may want to consider how it is handled in Therion (I've been using therion's QMs lately) so we devise something marginally compatible. Of course, Therion does it in a completely different way, so it may well be impossible.

Pulling out my trusty therion book:

centreline
  ...
  station <station> <comment> [<flags>]
  ...
endcentreline

set the station comment and its flags. If "" is specified as a comment, it is ignored. Supported flags: entrance, continuation, air-draught[:winter/summer], sink, spring, doline, dig, arch, overhang. Also not is allowed before a flag, to remove previously added flag.

In addition, continuation supports the explored attribute and arbitrary custom attributes. A typical example would be station 2 "nasty side crawl, goes 70ft or so" continuation explored 70ft attr code C. Anything added as attr <attrname> <attrvalue> can be pulled out by therion later: export continuation-list is very handy and generates an html table of QMs with all attributes. (I've started putting "height" and "width" attributes into my therion QM lists as well).

I don't think this is semantically a good fit with survex, and it has a lot of keywords that don't seem very useful. But allowing "arbitrary" fields has a certain utility to it, even if it's not convenient to implement.

The main problem is I don't think there's really a standard system for QM ranking, though using letters with A being best seems quite common so we could support *qm <grade> <description> and allow OMIT (default: -) for <grade>.

We're defining a "base featureset" for future data use---most likely someone exports all their QMs into a sqlite database or a csv file and knows how to sort them based on their arbitrary keying, and we just need to give them useful fields and defined semantics. explored-length, grade, dimensions, and of course station are the ones I would use.

Maybe it should be tocommentall if it's going to read the rest of the line (to match ignoreall).

I think we should just require they be quoted. While it is intuitive that something parallel to ignoreall might exist, I really don't see a good usecase, while ignoreall can be handy for data conversion from e.g. Walls or compass. Plus, having multiple possible somethingall commands might lead to users boxing themselves in when reviewing data, should we add something like "leg comments". Regardless, allowing in-data comments is a good idea, and allowing inline comments is interesting.

I do wonder if inline comments changes comment "semantics" from a user perspective: if it's easy to add a comment to every station, I'll do it! But I don't want to render all the comments ("blue nailpolish tip of bolder") unless I'm clicking on a station then---I want to only render important comments, like "P30", "Unusual Fossils" or "Sketchy climb-up" which describe a feature of the cave you might want to see on an overview. Maybe we should have todesc for inline "description of station" and encourage *comment for "cave detail".

[Olly Betts]

I think we should just require they be quoted. While it is intuitive that something parallel to ignoreall might exist, I really don't see a good usecase

There's rather a lot of CUCC data which looks like this:

*data passage station left right up down ignoreall

18x     7       1       4       2.5     corner of chamber, old numbered station in 161
2       2       1.5     3.5     1.8     large boulder

We even suggest this approach in the Survex manual:

         Simple example of how to use this data style (note the use of    
         ignoreall to allow a free-form text description to be given)::
 
             *data passage station left right up down ignoreall               
             1  0.1 2.3 8.0 1.4  Sticking out point on left wall
             2  0.0 1.9 9.0 0.5  Point on left wall
             3  1.0 0.7 9.0 0.8  Highest point of boulder

It's much easier to update such data to get those comments attached to the stations if you can just change ignoreall to a new commentall (or whatever).

But even for new data having to put double quotes around comments seems annoying (and creates failing to close the quotes as a new thing to be able to get wrong). It's not hard to implement either.