KineBody

Movable 3D Human Model






KineBody Pro Instructions: Exporting & Importing Poses


Overview

With the Export/Import Poses feature, you can write pose data to, and read from, an editable text file. This capability is designed as a way to introduce pose data from an external source into KineBody, or to use KineBody pose data in an external application.

A KineBody ‘pose’ file contains numeric values representing 1 or more KineBody poses, including body position & orientation (6 degrees of freedom (DOF) total), plus euler angles for joint rotations, for all joints & their active degrees of freedom. It also provides ‘descriptor’ strings to indicate joint & DOF names, to assist you in locating specific joint data. The pose file doesn’t include fixed joint parameters, such as range of motion, position or orientation of the joint axes, & euler ‘sequence’.

For exported posefiles, you can select from either of 2 sign conventions for joint angles:

The content & format of the export/import file is described in the lower part of this page.


Instructions

Locate controls: Controls for exporting & importing pose data are located in the ‘Save & Restore’ panel at the right side of the window. At the bottom of that section, click the black downarrow to expand the panel, showing a section with a yellow background.

The section includes a ‘multiple-select’ menu at the top, and buttons to Delete* or Export poses selected using that menu. Next to the Export button is a textbox, where you can enter a filename for the export file. The Import button, at the bottom, works independently of the multiple select menu. [The menu in the yellow section is only intended for selecting poses for Delete or Export operations – Note that there’s another menu just above, labeled ‘View a stored pose’, which contains an identical list of stored poses, but it’s only used for viewing the poses.]


Export poses: Before you can export a pose, it must first be named & saved into the KineBody repository. Instructions for these operations are provided here: Pro Instructions: Saving Poses (also accessible via the Help menu, under ‘Pro Operation’).

To export poses, select the poses by name from the menu in the yellow section. You can select 1 or more poses to export – use the Shift or Ctrl keys to help select multiple poses. Next, you can optionally change the name of the export file, by entering a new name into the box to the right of the Export button. This file will be saved to your browser’s ‘Downloads’ folder (pls see your browser documentation if you wish to change that location).

You select the sign system when you press the Export button, as follows:
> 'Normal' press: selects Anatomical signs (where possible, see below).
> [Ctrl]-press: selects RH signs (for all DOFs).

In either case, when you press Export, your browser will treat this operation similar to downloading a file from the internet: for instance, Chrome will launch a bar showing downloaded filenames, and show an animated arrow indicating a download has occurred. Then you can click on the filename to open, inspect and/or edit the file (in a text editor).


Modify poses: You can manually modify exported poses, using any text editor. If the file was generated by KineBody, it will include joint and DOF (degree of freedom) names to help you locate the desired values.

If necessary, use the KineBody app to confirm the names of the joints: they’re the same names listed in the ‘Moving joint’ menu (within the Move subpanel). You can also confirm the joint name in the ‘Pointing at’ box, by hovering the cursor over the segment distal to the joint and pressing the [Ctrl] and [Alt] keys. To confirm the DOF names, inspect the joint sliders that appear when you select a joint (from the Moving joint menu): the DOF names are identical to the slider labels. You can correlate DOFs with rotation axes by color: the color bar atop each joint slider matches the rotation axis color as it appears in the viewing area.

When changing angle data, take care to check which sign system is being used, as listed in the ‘Signs: **….’ field (the field provides a brief description of the sign system). If the RH system is used, you can also check the ‘sign suffix’ value ( ±1 ) for each DOF you plan to modify: values of -1 indicate that the RH directions are opposite to the those of the anatomical directions, listed in the DOF name in 'negative/ positive' order.

You can create a new pose file using data from some other source, by creating & using a custom-built application to do the conversion. In both cases, you must maintain the format of the pose data, in the following regards:

  1. Don’t add or remove any square brackets or commas, anywhere in the file. (These are essential for defining a legal JSON data structure, which is used to simplify the code for importing data).
  2. Don’t add digits to any numeric values, if they’re shown at full precision. This will mess up the JSON import.
  3. Don’t remove any joints, to shorten the list. (The input routine assigns the angle data to joints by their position in the list, not by joint name or number).
  4. Be sure to include a file format version number (currently 'v02') at the start of the file, just before the 1st '['.
  5. Include either "Signs: An" or "Signs: RH" at the bottom of the file, to indicate which sign system to use.

If you’re building your own converter app, you can simplify the process somewhat, by omitting or reducing some of the pre-defined text content, as follows:

  1. The opening header (‘ This is an editable …unchanged !’ ) and appendix (‘Units…’) can be omitted entirely. Don’t remove the string ‘v01’ (possibly with different digits) !
  2. The descriptors (joint & DOF names, & joint numbers (2-110)) and time stamp (‘180901 120000’) can be replaced by empty strings (“”) (i.e., keep the double quotes intact).


Import poses: To import poses: Click the Import button, which opens a dialog box to request a filename & its location. After you select the file, the import is automatic: you don’t need to do any further steps, although it's a good idea to confirm that the poses were correctly added to the Repository: just check at the bottom of the ‘Select pose(s):’ menu for new names.

Note that each imported pose is given a new numeric suffix (‘-xxx’), which is appended to the posename listed in the file (FFI: see https://www.kinebody.com/docs/ProInstructions.php#savpos). If the posename in the file already has a 3 digit suffix, that suffix will not be replaced upon import. Instead, you’ll get a posename with 2 suffixes, which may be useful if you’re trying to track the processing history of a pose. You can avoid having multiple suffixes by removing the old ones while editing the pose file.

Also: when importing pose data, the sign system (Anatomical or RH) is defined within the pose file. The signs of the angles are automatically adjusted as necessary before the pose is saved to the repository. (Note: the automated conversions require that the file version string (‘v02’ or ‘v01’) be present in the file. If this string is missing, an error will show, and the data will not be imported.)


Sign Conventions

This section provides additional detail about the two possible sign systems (Anatomical v. Right-Handed (RH)) available when you export poses.

Right-handed sign system: The axes for each KineBody joint (depicted by the magenta, yellow, and cyan lines) each have a positive direction, which make it possible to define positive rotation directions, using the ‘Right Hand Rule’: by pointing one’s right thumb in the positive axis direction, the right fingers point in the positive rotation direction.

The positive direction for each joint rotation axis matches that of the most closely aligned global position axis, when the body is in its ‘home’ position (facing forward, all joints at 0 degrees). The global position axes are horizontal (x), vertical (y), and the ‘negative’ distance (z); these are positive along screen directions to the right, upward, and toward the viewer, resp.

For example, the left gleno-humeral joint has 3 rotation axes (see Figure): extension/flexion about the magenta axis, adduction/abduction about the yellow axis, and internal/external rotation about the cyan axis. When the body is in the home position the magenta axis is most closely aligned with x, cyan with y, and yellow with z. Since the magenta axis is closest to ‘x’, the positive direction for that axis is to the right. Correspondingly, by the Right Hand Rule, the positive direction for rotations about that axis is such that the anterior aspect of the bone moves downward, i.e., the positive direction is extension.

(Caveats: i) owing to the use of Euler angles, the rotation axes may not remain orthogonal, when the joint is rotated. ii) The axis colors (magenta, yellow, cyan) are often ordered to correspond with the x,y,z directions, but this isn't consistent. (It actually doesn’t matter, regarding the sign conventions). iii) the axes are colored somewhat brighter in one direction, and darker in the other. This effect is subtle, and was originally intended to indicate positive & negative directions for those axes. However, the light/dark tones may be inconsistent, so they should be disregarded. Instead, use the method described above, matching each axis to the nearest position axis).

Anatomical sign system: Although the signs used in the Right-Handed system are consistent throughout the body, this can sometimes cause confusion: for example, 'abduction' is regarded as positive at the right shoulder, but negative at the left shoulder. Or, flexion is taken to be negative for cervical joints, but positive for lumbar joints. To bypass these situations, KineBody features an 'Anatomical' sign system, to represent anatomical movements of the same name with the same sign, wherever feasible, e.g., abduction is positive regardless of left or right side. Anatomical signs are used not only for exporting & importing poses, but also for all the joint movement sliders. This gives you a way to verify the directions for any anatomical movement, i.e., values appearing on the sliders are Anatomical.

When the anatomical sign system is used, the positive direction is included in the 'descriptor' string for each joint, in the exported pose file. For example: the descriptor string for gleno-humeral (L) is: " 16 gleno-humeral (L): [extension/flexion,int/external rotation,adduction/abduction ]". When the DOF names include movement terms separated by a ‘/’, such as ‘extension/flexion’, the directions are ordered as ‘negative / positive’, so in this example, extension is regarded as negative, flexion as positive.

You may notice that some of the DOF names don't use two slash-separated names; for example, ‘axial rotation’or ‘lateral flexion’. In these cases, there is no special anatomical sign convention; rather, positive & negative directions are defined using the Right Hand Rule. Thus for example, ‘axial rotation’ is typically defined for rotations about a vertical (y) axis; then, positive rotation is counterclockwise when viewed from above (or equivalently, the anterior aspect of the associated bone(s) moves to the right).

At this point, it's important to clarify that, when you select RH signs for the export file, you're selecting to use that system for all the joint DOFs in the file. By contrast, when you select the Anatomical signs, you're selecting to use that convention wherever possible, but it doesn't apply to all DOFs !! Rather, some of the DOFs will use the RH convention, as it's the only one available. In short, you should regard the choice of Anatomical system as an abbreviation, for 'Anatomical signs, wherever possible, otherwise RH signs'.

Pose files exported using the RH system contain additional information in the joint & DOF name string, to help clarify the signs. Following the DOF names is a ‘sign suffix’ string, such as ‘*[ -1,1,1 ]’. The 3 values are associated with the 3 DOFnames, respectively, and indicate that the movement names are ordered as ‘negative/ positive’ (for entries = 1) or ‘positive/negative’ (for -1). For example: if the posefile entry for gleno-humeral (L) is: [-35 ,0, 25]," 16 gleno-humeral (L): [extension/flexion,int/external rotation,adduction/abduction ]*[-1,1,1] then the extension/flexion value has an associated sign suffix of -1, meaning that extension is regarded as positive. Thus, the value (-35) represents 35deg of flexion. By contrast, the adduction/abduction value (25deg) has an associated suffix of 1, meaning that abduction is positive: In this case, the joint shows 25deg of abduction.

Pose files exported using the Anatomical system do not contain sign suffix strings; in this case, the movement names are ordered ‘negative/positive’ throughout the file.


Pose File Format

A KineBody Pro pose file contains numeric values representing 1 or more KineBody poses, for body position & orientation (6 DOF tot), plus euler angles for joint rotations, for all joints & their active degrees of freedom, plus descriptor strings to indicate joint & DOF names

(A pose file doesn’t include: joint parameters, such as range of motion, position or orientation of the joint axes, or euler configuration)

A pose file is formatted as plain text, structured in a ‘JSON’ format, as a series of nested arrays. Content within the JSON/nested arrays is as follows:



          [         // start of top level array
                     [         // start of data for 1st pose

                                [ posename, timestamp] ,

                                [         // start of section for body position & orientation data

                                           [ [ horiz, vert, dist ] , descriptor string ] ,
                                           [ [ spin, tilt, dial ] , descriptor string ]

                                ] ,         // end of body position & orientation data

                                [         // start section of joint angle data: (the θ's represent generic angles; the DOF names indicate which is which).

                                           [ [ θ1 , θ2 , θ3 ], descriptor string ] ,         // data for 1 joint, 1 to 3 DOF
                                           [ [ θ1 , θ2 , θ3 ], descriptor string ] ,         // data for 2nd joint, 1 to 3 DOF
                                           …
                                           [ [ θ1 , θ2 , θ3 ], descriptor string ]         // exactly 109 jts total

                                ]         // end joint angle data

                     ] ,         // end of data for 1st pose

                     [ data for 2nd pose ] ,
                     …
                     [ data for last pose ]         // any number of poses (subject to repository size limits)

          ]         // end of top level array


Notes:

1) Descriptor strings: all numeric triples are followed by a string, describing:

2) Blank DOF names represent unused DOFs: e.g. [ a, , b] represents a joint with just 2 DOF. Note! the numeric angle value for any unused DOF should be left = 0.

3) Units: angles in degrees, lengths in meters.

4) Axes, References, & Polarities:

a) Body position (horizontal, vertical, & distance): positive directions are defined relative to the screen:

b) Body orientation angles (spin, tilt, dial) (*)

Spin & dial polarities: for tilt angle in the range ±90°:

Note however, that both of these relationships are inverted, when the tilt angle is beyond ±90°. This is a consequence of KineBody Pro's 'casual mode' for body orientation angles, which allows you to tilt the body smoothly over a full rotation range (±180°), without abrupt jumps in the angle values. FFI: see the discussion of Casual mode.

* This discussion of body angle polarities presumes the body is posed with all joints in their 'home' positions, i.e. standing straight with arms & legs 'flat' in a common frontal plane. For the more general case, the spin, tilt and dial angles apply to the ribcage only, and the polarities described above should be understood as if the limbs extended from the ribcage in the same flat/frontal plane (regardless of their actual orientations).

c) Joints: Please see the Sign Conventions discussion above.

5) The selected sign system is saved into the exported file, in the string ‘Signs: Anatomical …’ or ‘Signs: RH…’ If this field is missing, the sign system defaults to ‘Anatomical’. For generating a pose file programmatically, it’s sufficient to include just the 1st two letters: ‘Signs: RH’ or ‘Signs: An’.

6) Interphalangeal joints, distinguishing hand v finger : these joint names are the same for hand & foot, so you should distinguish them by joint 'number' preceding the joint name:

e.g., " 54 distal interphalangeal 3 (L): ..." is a hand joint.

7) Neck & lumbar spine joints: In each of these sections, one joint cannot be moved independently. In the neck, you cannot move the Occiput-C1 joint, because the control mechanism for that joint has been redirected to handle movement of the entire neck. This is evident in the joint names:
          3 neck (Occ-C1, C1C2, ..., C7T1) // all neck joints, not just Occ-C1
          4 C1C2 (atlanto-axial)
          5 C2C3
The same holds for L5S1 in the lumbar spine.