1 (edited by arnopluk 2018-Feb-08 12:30:59)

Topic: Documentation for custom tools

Hello Joan,

I'm playing around with the custom tools, a very nice feature of Kinovea! I'm using Kinovea 0.8.26 64bit.
Unfortunately, I couldn't find that much documentation about the xml format of the files. So far, I've run into a couple of things I can't get a grip on right now:

  • Is it possible to specify the position of labels for angles (like 'radius')?

  • With 'optionGroup' you can specify options which can be selected by the user. Can you specify the default options which are used? (In Human Model 2 I found the keyword 'DefaultOptions', but no example how to use it.)

  • I would like to have 2 constraints in effect for my handle: 1. Fixed length ('DistanceToPoint') and 2. Rotation in steps of 5 degrees ('RotationSteps'). However, only the constraint that is configured last, is used by Kinovea.

  • Is it possible to lock handles so they can't be changed by the user?
    For example: Lock the angle-to-vertical of a certain line, while allowing a user to change its length.

  • Can the position of annotation in the capture screen be saved?
    For example: Default annotation in a fixed-camera setup.

  • (edit) How can I make my own icons for the custom tools?

Regards,
Arno

Re: Documentation for custom tools

Cool! I also think it's one of the most powerful feature in the program, but yeah the documentation is certainly lacking.
I will get around to at least write a page with a raw list of each node and the attributes they support.

If you haven't seen it already, here is an article discussing custom tools: http://www.kinovea.org/en/creating-a-custom-tool/

arnopluk wrote:

Is it possible to specify the position of labels for angles (like 'radius')?

No, at the moment the text distance is hardcoded. It's a good point though, I'll add that to the backlog for the next version.

arnopluk wrote:

With 'optionGroup' you can specify options which can be selected by the user. Can you specify the default options which are used? (In Human Model 2 I found the keyword 'DefaultOptions', but no example how to use it.)

Yes. I'll recap how this works for everyone and then add more details on declaring default options.

Each object visibility (objects: segment, handle, ellipse, angle, distance, position, computed point) can be controlled by named "options". These options end up in the context menu of the drawing and can be toggled on/off by the user. Options can also control the enabling of "constraints" placed on handles, such that the handle can be freely moved or constrained based on user desire.

This is controlled by specifying optionGroup="name of option" as an attribute on the object. Multiple objects' visibility or constraints in different objects can be controlled by the same option. There can be multiple options in the drawing.

Option discovery is entirely based on the textual name so be sure to correctly copy & paste the name otherwise they will end up as two different options.

By default all options are "off". To specify default options that are "on", create a "DefaultOptions" node and add the named options under "OptionGroup" subnodes, as following:

<DefaultOptions>
    <OptionGroup>Display ankle angles</OptionGroup>
    <OptionGroup>Display hips angles</OptionGroup>
</DefaultOptions>

Options listed here that are not matched to an option declared elsewhere will be ignored.

arnopluk wrote:

I would like to have 2 constraints in effect for my handle: 1. Fixed length ('DistanceToPoint') and 2. Rotation in steps of 5 degrees ('RotationSteps'). However, only the constraint that is configured last, is used by Kinovea.

Yes you are right. I didn't anticipate that use-case, all the other constraints are mutually exclusive I think, but rotation steps could be combined with others. This is not possible at the moment.

arnopluk wrote:

Is it possible to lock handles so they can't be changed by the user?
For example: Lock the angle-to-vertical of a certain line, while allowing a user to change its length.

For that specific scenario I think you could use a "LineSlide" constraint, where a handle is only allowed to move along a line defined by two other points. The LineSlide constraint takes "point1", "point2" and "position" attribute. The "position" attribute further determines where the handle can go in relation to the two existing points, and can take the following values: BeforeSegment, BeforeAndOnSegment, OnSegment, AfterAndOnSegment, AfterSegment, Anywhere.  Check the "Archery top view" tool for an example.

So you would first make sure your have two points defining the fixed-angle line in the point list  (without necessary creating a visible segment from them). Then add a third point and a handle referencing it, with a constraint that only allows it to slide along the line defined by the other two, maybe using AfterAndOnSegment. Then you can create a segment object that goes from the angle origin to the sliding point.

I just realized that creating a completely locked point is harder than necessary. You can create a "Point" but it won't be visible until it's either a handle or a computed point. Right now the only way seems to be to create two dummy points and create computed point based on them. Or maybe a collapsed segment. I should probably add a simpler constraint that completely locks a handle in place.

How can I make my own icons for the custom tools?

The gist of it is that the "Icon" node contains the Base64 encoded image. In practice:

Can the position of annotation in the capture screen be saved?
For example: Default annotation in a fixed-camera setup.

You can have a KVA file that is always loaded when you open a camera.

Create the annotations in the playback screen (maybe by reloading a video captured from the camera for alignment) and save them to a KVA file named "capture.kva" (File > Save > Save only the analysis). Then place that file in Kinovea %appdata% directory. The location of this directory depends on whether you are running the installed or zipped version, but you can get to it from menu Help > Open log folder.

The same can be done for the playback screen using "playback.kva". It's an application-wide thing though, there is currently no support for per-camera default KVA.

Re: Documentation for custom tools

Hi,

I have addressed the following points for the next release:

1. Position of the text for angles

There is now a "textDistance" attribute on the angle node.

<Angle origin="1" leg1="2" leg2="3" signed="true" ccw="true" supplementary="false" radius="0" textDistance="40" tenth="true"/>

2. Double constraint fixed length + rotation steps.

The rotation steps constraint now has an attribute "keepDistance" that will force the point to stay at the same distance from the origin. I think it still didn't make sense to have a full multi-constraints system, as this was the only meaningful combination of two constraints.

<Constraint type="RotationSteps">
        <RotationSteps origin="1" leg1="0" step="5" keepDistance="true" />
</Constraint>

Note that the existing "DistanceToPoint" constraint supports the SHIFT modifier that forces segments to lock onto 45° steps. This is supported out of the box and doesn't need any specifics in the tool file.

3. Completely locked points.

There is now a "LockedInPlace" constraint that will simply ignore the applied motion.

<Constraint type="LockedInPlace" />

In addition to that, there is now a debug mode for the custom tools. It will be available from menu Options > Preferences > Drawings > General, check box "Custom tools debug mode". It will show the points ids, the segments ids and names, and angles ids and parameters. Counting starts at 0.

http://www.kinovea.org/screencaps/0.8.27/customtooldebug3.png