Add speed, distance and angle for observations

[yliefting]

In Agouti, we have implemented the tools for animal tracking by Rowcliffe et. al. (https://github.com/MarcusRowcliffe/CTtracking) into the application. With these tools, users can record the position of an animal in the frames of a sequence. These positions are then used to automatically calculate the speed, distance and angle of the animal. I won't describe all the details here, but we propose to include this information in camtrap-dp.

The addition would be the addition of three fields to observations.sql: speed - average movement speed (km/h) of the animal in the sequence, based on the frames in which the animal was marked. distance - horizontal distance (m) of the animal from the camera, for the frame in which the animal is first tagged. angle - angle of the animal, from the camera view centerline, for the frame in which the animal is first tagged.

This output can already be used in analysis tools to estimate abundance with, for example, the Random Encounter Model of Rowcliffe et. al.

[peterdesmet]

@yliefting can you clarify for the 3 fields - if applied to a sequence of images - whether it is an average value or the value in e.g. the first image?

[kbubnicki]

I think this needs more discussions e.g. distance and angle can also be assessed for single images (media-based approach), then it makes little sense to me to define it only for the first frame in a sequence. Also animal speed can be estimated for a single video file (which is of course a sequence of frames). But maybe this is only about clear and correct definitions for all these fields? @yliefting @peterdesmet

[peterdesmet]

We definitely need the fields for use cases already in use. I’ll try and craft better definitions.

[MarcusRowcliffe]

Please implement with the name radius instead of distance for the new field

[peterdesmet]

@MarcusRowcliffe can you clarify or suggest a definition? Would the unit still be meters?

[MarcusRowcliffe]

radius should indeed be in meters; angle should be in radians, and it's definition should be refined as "angular distance from the centre line of the camera field of view" (or something to that effect); speed should be in meters per second. In the observations table, radius and angle refer to the radial and angular distances of the animal in the first image of the observation. As @kbubnicki says, these values can indeed also be linked to specific images / frames, but it doesn't work to simply add them to the media table because a given image can have multiple positions digitised, and it is also important for analysis downstream to be able to link positions to observations. To achieve this, Agouti is now exporting an additional table called positions, which includes radius and angle for every point digitised in a project, indexed by observation. This is needed to complete the suite of density estimation tools, so will ultimately need to be readable by camtraptor. I'll post a separate issue about this.

[peterdesmet]

@MarcusRowcliffe I guess distance was named radius because it aligns better with angle? I don't find it immediately intuitive though, as in what is the "radius of an observation or animal"? Note also that it doesn't align well with detectionDistance. What do others think? Is it worth looking for a better name to describe "the distance of the animal to the camera" and "the angle between the animal and the centre line of the camera's field of view"?

[PietrH]

"the angle between the animal and the centre line of the camera's field of view"

This description reminds me of azimuth and relative bearing

[MarcusRowcliffe]

@peterdesmet I would prefer to stick with radius. The field names stem from the original publication where the utility of these data were first proposed (https://doi.org/10.1111/j.2041-210X.2011.00094.x), which uses radius and angle to describe exactly these data, and I think a conceptual connection with this source literature is helpful. Radius is commonly used to name this value in polar co-ordinate systems (which this is), so I don't think it should be completely strange. I see it as a benefit that the observation-specific field is clearly distinguished from the deployment-specific detectionDistance field, which has a very different definition. More pragmatically, the density estimation functions already use radius as the required field name (although it would not be hard to change this if necessary).

[timrobertson100]

offsetAngle (degrees) might be an alternative to consider - used in e.g. papers about detection from images using AI (example).

Bearing in mind I am a naive user I too find radius less intuitive than e.g. targetDistance. It may be relevant that there is quite some research on object "distance estimation" from images using AI (example) which seems to be largely using "distance" terminology.

With that said, I agree with @MarcusRowcliffe that tying it to what is commonly used / in literature is worthwhile.

[peterdesmet]

Discussed this with @MarcusRowcliffe in a call. Conclusions are:

Angle + Radius

• Are only required in the media-observations table. That's good news, because it avoids having them with confusing definitions in the event-observations table.
• Can replace the positions table in Agouti. The user-indicated x, y positions are not required info for further analysis, but useful metadata. Can likely be indicated in boundingBox (#219)
• Degrees is ok as unit for angle, m for radius
• It is necessary to know which image was first. Is possible with timestamp.
• It is necessary to know that angle/radius in media-obs 1 is about the same individual as in media-obs 2. It is therefore necessary to indicate the individualID
• The fields could appear just after individualID and for better reference be called:

individualID
individualAngle
individualRadius
# or
individualID
individualPositionAngle
individualPositionRadius

• All values are used in distance sampling
• The first values + speed are used for random encounter model (REM). The link with speed (see below) can be facilitated by camtraptor.

Speed

• Only makes sense in the event-observations table.
• Unit is m/s.
• To make the potential link with angle/radius in the media-observation table and to clarify that these fields are for individuals (not groups of animals) it is necessary to indicate the individualID.
• The field could appear just after individualID and for better reference be called individualSpeed. This in contrast with sex, lifeStage, behavior which can be used for groups.

@timrobertson100 @yliefting @jimcasaer @kbubnicki @damianooldoni can you indicate if you prefer the name individualAngle or individualPositionAngle?

[damianooldoni]

My two cents: 👍 for the longest but most precise definition, i.e. individualPositionAngle and individualPositionRadius. The reason: it is the only logic defintion, especially if we have something like individualSpeed in the other table. speed vs position, not speed vs radius or angle. We express position in angular notation, that means radius and angle are the two dimensions for describing the position.

[peterdesmet]

Fixed in Camtrap DP 0.6 #297.