Add support for polygonal objects in NOR

[davorvr]

Update to support NOR object specification as polygons with >4 points. Example of polygonal object specification in an arena text file (6 points), which always needs to have the polygon x1 y1 x2 y2 x3 y3 x4 y4 x5 x5 (...) format:

object.2 = polygon 741.7045593261719 246.5684509277344 757.9303894042969 249.91976165771484 797.8258666992188 210.4977264404297 790.0731201171875 194.2668609619141 770.2526245117188 194.2734832763672 737.9223327636719 230.29861450195312
novel.object.1 = polygon 892.5897216796875 87.07628631591797 923.9994201660156 86.71891403198242 932.1217651367188 63.780019760131836 928.904541015625 43.74013710021973 901.0473937988281 43.573068618774414 892.8282165527344 52.27064895629883

This change was done in three commits:

1. Added a universal transform method which supports any number of object points to replace square_transform,
2. Added a polygon function for storing polygonal objects (additionally, it always applies terra's convHull function before returning the object in case points are specified out of order),
3. Updated NOR code to support arena text files with the polygon object specification.

This change implements functionality talked about recently in #8.

[davorvr]

Resulting zones don't seem to be properly defined. Trying to fix...

[rupertoverall]

Thanks Davor for these contributions! I am travelling a lot over the next month, but I'll review this ASAP. The current implementation just does an affine transform, but it will be great to have full correction for off-centre cameras incorporated (also planned for circular arenas).

Note that the definition of arenas for the pre-defined experiment types is very rigid (open field MUST be square, MWM MUST be circular; and the size of the zones is not user-editable). This is by design so that the models are transferrable - otherwise the 'zero-config' workflow that makes Rtrack special won't work. The idea is to define new experiment types for customised tasks (this is planned for future versions but is a logistical undertaking that would require a fundamental rebuild of the R package - we have solutions in the pipeline though).

The polygon support is going to be most useful for defining complex zones in new arena types. This is where the development of Rtrack is heading, so you are preempting some of this work :)

[davorvr]

Thanks, happy to hear these changes could be of help. With these few modifications, the package is saving me a ton of work and particularly debugging for my own analysis of SLEAP-generated tracks, thank you for your work - the future of the package looks awesome :) The rationale for hardcoded parameters makes sense to me, though, to have Rtrack work with and produce fairly standardised experimental results (if I understood correctly), but I'd just like to ask, which models are you referring to that are intended to be transferrable?

Also, I'm getting weird results with my fork, time.in.object.vicinity doesn't seem to correspond to the sum of time spent in object 1 vicinity and object 2 vicinity (which, from what I gathered, encompasses both the area of the object itself, and its vicinity). time.in.object.vicinity is always larger, I'm not quite sure why this happens. Example output of a results spreadsheet with code modified to output time for both object.1 and object.2 in addition to novel.object and object:

time.in.object.1.vicinity	time.in.object.2.vicinity	time.in.object.vicinity	time.in.novel.object.vicinity
24.5143954951971	18.7487424091863	55.7484730043061	24.5143954951971
20.5097901277993	11.6693633485754	42.9644741470278	20.5097901277993
10.2115145345549	15.3591222712363	42.7711797307997	10.2115145345549
24.2624659919469	14.5412776145391	58.9752094896071	24.2624659919469
20.7345654512851	11.946405260012	43.9865726240287	20.7345654512851
28.1713446475196	4.8717362924282	50.8778720626632	28.1713446475196
14.8478831168831	13.3672077922078	41.4589090909091	14.8478831168831

I've noticed a footnote in the documentation where the sum might not work out in case of object vicinities intersecting, but this is not the case in my polygonal setups:

[rupertoverall]

The 'models' refer to the strategy-calling functionality for MWM and Barnes maze. This does not (yet) affect the open field or NOR arenas.

[rupertoverall]

I will have a closer look at the time.in.vicinity issue—this is not something that has come up in testing so far.