anispace (development version)
Added
quat_from_vectors(primary, secondary, axes)builds the orientation whose body axisaxes[1]points alongprimaryand whoseaxes[2]points towardssecondary, using only the part ofsecondaryperpendicular toprimary. Three points define an orientation this way: one axis from the first point to the second, and roll fixed by any third point off that line. It is the primitive behind animetric’s plannedadd_orientation()(animovement/animetric#97). Rows with a missing or zero vector, or parallel vectors, giveNA.transform_to_egocentric(align = "orientation")aligns each subject by its own declared orientation (#49). Alignment used to need two or three keypoints defining an axis. Many datasets have none but do record an orientation: FicTrac, rigid-body motion capture, or a centroid with a heading. Where both exist, the measured orientation is often better than a noisy keypoint axis. The frame is centred onto, then each subject at each moment is turned by the inverse of itstomember’s orientation, so it faces +x. In 2D that is a rotation by-yaw, after whichyawis exactly 0. In 3D it is the inverse quaternion, after which the body axes lie along the coordinate axes and the orientation is the identity.align_perpendicularfaces it across, as for keypoints. A moment whosetomember has no orientation comes backNA, not unrotated. A single value can never be alignment points, so"orientation"is unambiguous even when a member has that name.Quaternions for 3D orientation (#7):
quat_multiply(),quat_conjugate(),quat_normalise(),quat_rotate()andquat_distance(); conversion withquat_from_axis_angle()/quat_to_axis_angle(),quat_from_matrix()/quat_to_matrix()andquat_from_euler()/quat_to_euler()(all twelve sequences, withsequenceandintrinsicalways stated); andquat_slerp(),quat_mean(),quat_continuous()andquat_angular_velocity().transform_euler_to_quaternion()turns exported Euler angles into a declared quaternion orientation (animovement/anicore#46), records their convention, andtransform_quaternion_to_euler()gives them back as a derived view, in the recorded convention unless another is given.
Changed
Breaking:
phichanges range.map_to_polar(),map_to_cylindrical()andmap_to_spherical()writephiin(-pi, pi], or(-180, 180]in a degrees frame, instead of[0, 2 * pi)(#59). So doescartesian_to_phi(), in radians. This is the signed range the suite uses for every direction (animovement/anicore#181), sophinow reads like a heading or a course: a point below the x-axis has a negative azimuth, and a point on the negative x-axis haspi. No direction changes, only how it is written, andmap_to_cartesian()reads either range. For the old range, wrap at the end:anicore::wrap_angle(phi, "2pi")in radians, orphi %% 360in a degrees frame. If you installed a development version from r-universe, check any code that assumesphiis non-negative (a test such asphi > pi, or binning directions over[0, 2 * pi)): it still runs, but now gives different answers for points below the x-axis.Help pages show each function’s lifecycle stage (animovement/.github#46). An unlabelled function is stable, and changes only through a deprecation cycle. Five new interfaces are labelled experimental, so they may still change without one:
transform_euler_to_quaternion()andtransform_quaternion_to_euler(),quat_from_vectors(),quat_angular_velocity(), andtransform_to_egocentric(align = "orientation"). The rest of the quaternion toolkit, and aligning on members, are stable.Works with anicore’s
anipointclass and rebuilt accessor API (animovement/anicore#154). The transforms now require an anipoint, so the error for other input reads “not an anipoint”.
Fixed
rotate_coords(), and through ittransform_to_egocentric(), rotate a declared orientation along with the positions (#49). They turned the positions and leftyawor the quaternion as it was, so the two disagreed: aligning a body on its tail-to-head axis put the head on +x whileyawstill gave its old heading. The orientation is now turned by the same rotation, per subject and moment. In 2D the rotation’s angle is added toyaw, in the frame’sunit_angle, and wrapped to the range the input used — signed if any value is negative, asanicore::reflect_axis()decides it. In 3D the quaternion is pre-multiplied by the rotation’s, which is the side a rotation in the frame’s coordinates goes on; the quaternion help now says so. The centre of rotation (about) plays no part, and a moment left unrotated for want of an alignment point keeps its orientation as it keeps its positions.translate_coords()leaves orientation alone, as before.rotate_coords()gives every moment its own rotation even when some have none. A moment whose alignment point was missing dropped out of the list of rotations rather than holding a place in it, so when it was the last moment the list came up short: with two moments the first’s rotation was recycled onto the second’s rows, and with more the call failed with “Assigned datarotationsmust be compatible with existing data”. The alignment points were also paired up by row position rather than by moment, so a member with no row at some moment failed with “non-conformable arrays”, or, with equal counts, paired one moment’s point with another’s. They are now matched on the moment, and a moment without one is left unrotated, as was intended.map_to_cartesian(),map_to_polar(),map_to_cylindrical()andmap_to_spherical()honour the frame’sunit_angle(#47). They treated every angle as radians, so a frame declared in degrees converted wrongly:phi = 90was read as 90 radians, andmap_to_polar()wrote radians under a"deg"label. A frame that arrived in degrees, from a reader or fromanicore::convert_unit_angle(), came out wrong. A round trip only looked right because both directions made the same mistake. They now read and writephiandthetain the frame’s unit, throughanicore::angle_to_rad()andanicore::angle_from_rad()(animovement/anicore#170). The component converters (cartesian_to_phi(),polar_to_x(), …) stay in radians.The same functions read their input columns from the frame’s declared axes, so they work on frames whose columns are not called
x,y,z,rho,phiandtheta. They used to stop with “Columnrhonot found”. A cylindrical frame’szkeeps its column name through both directions.
Removed
The deprecated
centeredargument ofcartesian_to_phi()is removed (#59, #63). The result is always in(-pi, pi], whichcentered = TRUEused to ask for, so dropcentered = TRUE. For the[0, 2 * pi)thatcentered = FALSEgave, useanicore::wrap_angle(cartesian_to_phi(x, y), "2pi")instead.-
calculate_angular_difference()anddiff_angle()move to anicore, ascirc_difference()andcirc_successive_difference()(animovement/anicore#147). Both are general-purpose circular primitives rather than spatial transforms — the shortest signed distance between two angles, and that distance applied along a vector — andcalculate_angular_difference()was already a one-line wrapper overanicore::wrap_angle(). anicore owns the angle utilities, and keeping the circular family together means it can be split out on its own later without unpicking anispace.The new names follow anicore’s convention:
circ_*()computes with the wraparound,*_angle()manipulates how an angle is written. Callanicore::circ_difference()andanicore::circ_successive_difference()instead; both are attached bylibrary(animovement), so a script using the metapackage needs no change.
anispace 0.3.0 (2026-08-28)
Changed
The transforms read the frame’s declaration instead of naming its columns (#20).
translate_coords(),rotate_coords()andtransform_to_egocentric()tookindividual,keypoint,time,x,yandzliterally, so a frame declaring anything else failed outright. They now resolve identity throughvariables_what, the index throughget_index()and the coordinates throughget_axes().The reference point is a member of any identity level, not a keypoint (#20).
to_keypointbecomesto,alignment_pointsbecomesalign, and a newlevelsays which identity variable they name members of — so a group centre can be taken onindividualas readily as onkeypoint.leveldefaults to the frame’s only identity variable; a frame declaring several has to be told, sincevariables_whatorder is not something to rely on (animovement/anicore#140, animovement/anicore#141).translate_coords()takesby, a named offset per axis role, in place ofto_x/to_y/to_z.rotate_coords()takesabout, the centre of rotation — a member to turn around, or a fixed point. It defaults to the coordinate origin, which is what the previous behaviour was, unstated.transform_to_egocentric()’salignis optional. Omitted, the frame is re-centred without being reoriented.A quarter turn follows the frame’s declared sense of rotation (#29, in part).
align_perpendicularturned one way regardless; on a frame whose axes say its angles run clockwise it now turns the other. Themap_to_*()half of that issue is still open.wrap_angle()andunwrap_angle()move toanicore, which already helddeg_to_rad()andrad_to_deg()(animovement/aniframe#128). They are angle arithmetic rather than coordinate transformation. Useanicore::wrap_angle().The minimum
anicoreis 0.8.0, which is the first version published under that name — the dependency was renamed without a version constraint, so nothing recorded that a pre-renameaniframewill not do.The core data structures come from
anicore, which is what theaniframepackage was renamed to in its 0.8.0 (animovement/anicore#84). Theaniframeclass keeps its name; only the package providing it changed.
Fixed
-
map_to_polar(),map_to_cylindrical()andmap_to_spherical()declare the system they mapped to (#27). They returned frames whose metadata still described the system they came from —variables_wherenamingxandyon a frame that no longer had them, andcoordinate_systemstillcartesian_2d, whichvalidate_aniframe()rejects outright.It went unnoticed because
ensure_is_polar()matched column names, sorhoandphibeing present satisfied it whatever the metadata said. Those predicates now readcoordinate_systemand fail correctly. The trailingas_aniframe()would have re-derived the declaration, but it runs after the check, so the check had never validated the object being returned. Rotating a frame with more than one temporal group no longer multiplies its rows (#20).
rotate_coords()joined the rotation angles by the index alone, so every trial’s angle matched every trial’s rows: two trials turned 12 rows into 48, of which 36 were duplicates. It returned plausible-looking data rather than an error. The standing# TODO: Will likely break with multiple trialsis resolved.Rotating three-dimensional coordinates works (#4). It aborted with “not yet supported”. Two alignment points give the minimal rotation onto the target axis, leaving the roll about it as it was; a third fixes the orientation outright. Two dimensions are the same code with the rotation axis fixed to
z.translate_coords_keypoint()looped with1:length(), which runs twice on empty input (#15). The loops are gone entirely, replaced by grouped operations.-
map_to_spherical()returns the radial distance from the origin asrho, rather than the cylindrical radius (#19).thetaalready used the full radius, so the triple was inconsistent with the name; ISO 80000-2 uses the radial distance. This was lossy as well as non-standard — a point on the z-axis has a cylindrical radius of zero, so(0, 0, 5)round-tripped throughmap_to_cartesian()to the origin, and now returns(0, 0, 5).spherical_to_z(rho, theta)is nowrho * cos(theta)where it wasrho / tan(theta). Code readingrhofrom a spherical frame, or callingspherical_to_z()directly, needs updating.map_to_cylindrical()is unchanged:rhothere is the distance from the z-axis, which is correct for a cylindrical frame.
anispace 0.2.0 (2026-08-18)
First tagged release. anispace had been usable for a while but was never tagged, so this marks the current state rather than a change in it.
Added
- Coordinate-system conversion:
map_to_cartesian(),map_to_polar(),map_to_cylindrical()andmap_to_spherical(), with the element-wise helpers behind them —cartesian_to_rho(),cartesian_to_phi(),cartesian_to_theta(),polar_to_x(),polar_to_y()andspherical_to_z(). - Angular arithmetic:
wrap_angle(),unwrap_angle(),diff_angle()andcirc_difference(). - Rigid transformations:
rotate_coords(),translate_coords()andtransform_to_egocentric().