BLI_math_rotation.h

Go to the documentation of this file.

/* SPDX-FileCopyrightText: 2001-2002 NaN Holding BV. All rights reserved.
 *
 * SPDX-License-Identifier: GPL-2.0-or-later */
 
#pragma once

 
#include "BLI_math_base.h"       // IWYU pragma: keep
#include "BLI_math_constants.h"  // IWYU pragma: keep
#include "BLI_utildefines.h"
 
#include "DNA_vec_types.h"
 
/* -------------------------------------------------------------------- */
 
/* Initialize */
 
/* Convenience, avoids setting Y axis everywhere. */
 
void unit_axis_angle(float axis[3], float *angle);
void unit_qt(float q[4]);
void copy_qt_qt(float q[4], const float a[4]);
 
/* Arithmetic. */
 
void mul_qt_qtqt(float q[4], const float a[4], const float b[4]);
void mul_qt_v3(const float q[4], float r[3]);
void mul_qt_fl(float q[4], float f);

void pow_qt_fl_normalized(float q[4], float fac);
 
void sub_qt_qtqt(float q[4], const float a[4], const float b[4]);
 
void invert_qt(float q[4]);
void invert_qt_qt(float q1[4], const float q2[4]);
void invert_qt_normalized(float q[4]);
void invert_qt_qt_normalized(float q1[4], const float q2[4]);
void conjugate_qt(float q[4]);
void conjugate_qt_qt(float q1[4], const float q2[4]);
float dot_qtqt(const float a[4], const float b[4]);
float normalize_qt(float q[4]);
float normalize_qt_qt(float r[4], const float q[4]);
 
/* Comparison. */
 
bool is_zero_qt(const float q[4]);
 
/* interpolation */
void interp_dot_slerp(float t, float cosom, float r_w[2]);
void interp_qt_qtqt(float q[4], const float a[4], const float b[4], float t);
void add_qt_qtqt(float q[4], const float a[4], const float b[4], float t);
 
/* Conversion. */
 
void quat_to_mat3(float m[3][3], const float q[4]);
void quat_to_mat4(float m[4][4], const float q[4]);

void quat_to_compatible_quat(float q[4], const float a[4], const float old[4]);

void mat3_normalized_to_quat_fast(float q[4], const float mat[3][3]);
 
void mat3_normalized_to_quat(float q[4], const float mat[3][3]);
void mat4_normalized_to_quat(float q[4], const float mat[4][4]);
void mat3_to_quat(float q[4], const float mat[3][3]);
void mat4_to_quat(float q[4], const float mat[4][4]);
void tri_to_quat_ex(float quat[4],
                    const float v1[3],
                    const float v2[3],
                    const float v3[3],
                    const float no_orig[3]);
float tri_to_quat(float q[4], const float a[3], const float b[3], const float c[3]);
void vec_to_quat(float q[4], const float vec[3], short axis, short upflag);
void rotation_between_vecs_to_mat3(float m[3][3], const float v1[3], const float v2[3]);
void rotation_between_vecs_to_quat(float q[4], const float v1[3], const float v2[3]);
void rotation_between_quats_to_quat(float q[4], const float q1[4], const float q2[4]);

float quat_split_swing_and_twist(const float q_in[4],
                                 int axis,
                                 float r_swing[4],
                                 float r_twist[4]);
 
float angle_normalized_qt(const float q[4]);
float angle_normalized_qtqt(const float q1[4], const float q2[4]);
float angle_qt(const float q[4]);
float angle_qtqt(const float q1[4], const float q2[4]);
 
float angle_signed_normalized_qt(const float q[4]);
float angle_signed_normalized_qtqt(const float q1[4], const float q2[4]);
float angle_signed_qt(const float q[4]);
float angle_signed_qtqt(const float q1[4], const float q2[4]);

void mat3_to_quat_legacy(float q[4], const float wmat[3][3]);
 
/* Other. */

void sin_cos_from_fraction(int numerator, int denominator, float *r_sin, float *r_cos);
 
void print_qt(const char *str, const float q[4]);
 
#define print_qt_id(q) print_qt(STRINGIFY(q), q)

 
/* -------------------------------------------------------------------- */
 
/* Conversion. */
 
void axis_angle_normalized_to_quat(float r[4], const float axis[3], float angle);
void axis_angle_to_quat(float r[4], const float axis[3], float angle);
void axis_angle_to_mat3(float R[3][3], const float axis[3], float angle);
void axis_angle_normalized_to_mat3_ex(float mat[3][3],
                                      const float axis[3],
                                      float angle_sin,
                                      float angle_cos);
void axis_angle_normalized_to_mat3(float R[3][3], const float axis[3], float angle);
void axis_angle_to_mat4(float R[4][4], const float axis[3], float angle);

void mat3_normalized_to_axis_angle(float axis[3], float *angle, const float mat[3][3]);
void mat4_normalized_to_axis_angle(float axis[3], float *angle, const float mat[4][4]);
void mat3_to_axis_angle(float axis[3], float *angle, const float mat[3][3]);
void mat4_to_axis_angle(float axis[3], float *angle, const float mat[4][4]);
void quat_to_axis_angle(float axis[3], float *angle, const float q[4]);
 
void angle_to_mat2(float R[2][2], float angle);
void axis_angle_to_mat3_single(float R[3][3], char axis, float angle);
void axis_angle_to_mat4_single(float R[4][4], char axis, float angle);
 
void axis_angle_to_quat_single(float q[4], char axis, float angle);

 
/* -------------------------------------------------------------------- */
 
void quat_to_expmap(float expmap[3], const float q[4]);
void quat_normalized_to_expmap(float expmap[3], const float q[4]);
void expmap_to_quat(float r[4], const float expmap[3]);

 
/* -------------------------------------------------------------------- */
 
void eul_to_quat(float quat[4], const float eul[3]);
void eul_to_mat3(float mat[3][3], const float eul[3]);
void eul_to_mat4(float mat[4][4], const float eul[3]);
 
void mat3_normalized_to_eul(float eul[3], const float mat[3][3]);
void mat4_normalized_to_eul(float eul[3], const float m[4][4]);
void mat3_to_eul(float eul[3], const float mat[3][3]);
void mat4_to_eul(float eul[3], const float mat[4][4]);
void quat_to_eul(float eul[3], const float quat[4]);
 
void mat3_normalized_to_compatible_eul(float eul[3], const float oldrot[3], float mat[3][3]);
void mat3_to_compatible_eul(float eul[3], const float oldrot[3], float mat[3][3]);
void quat_to_compatible_eul(float eul[3], const float oldrot[3], const float quat[4]);
void rotate_eul(float beul[3], char axis, float angle);
 
/* Order independent. */

void compatible_eul(float eul[3], const float oldrot[3]);
 
void add_eul_euleul(float r_eul[3], float a[3], float b[3], short order);
void sub_eul_euleul(float r_eul[3], float a[3], float b[3], short order);

 
/* -------------------------------------------------------------------- */
 
/* WARNING: must match the #eRotationModes in `DNA_action_types.h`
 * order matters - types are saved to file. */
 
typedef enum eEulerRotationOrders {
  EULER_ORDER_DEFAULT = 1, /* blender classic = XYZ */
  EULER_ORDER_XYZ = 1,
  EULER_ORDER_XZY,
  EULER_ORDER_YXZ,
  EULER_ORDER_YZX,
  EULER_ORDER_ZXY,
  EULER_ORDER_ZYX,
  /* There are 6 more entries with duplicate entries included. */
} eEulerRotationOrders;

void eulO_to_quat(float q[4], const float e[3], short order);
void eulO_to_mat3(float M[3][3], const float e[3], short order);
void eulO_to_mat4(float mat[4][4], const float e[3], short order);
void eulO_to_axis_angle(float axis[3], float *angle, const float eul[3], short order);
void eulO_to_gimbal_axis(float gmat[3][3], const float eul[3], short order);

void mat3_normalized_to_eulO(float eul[3], short order, const float m[3][3]);
void mat4_normalized_to_eulO(float eul[3], short order, const float m[4][4]);
void mat3_to_eulO(float eul[3], short order, const float m[3][3]);
void mat4_to_eulO(float eul[3], short order, const float m[4][4]);
void quat_to_eulO(float e[3], short order, const float q[4]);
void axis_angle_to_eulO(float eul[3], short order, const float axis[3], float angle);
 
/* Uses 2 methods to retrieve eulers, and picks the closest. */
 
void mat3_normalized_to_compatible_eulO(float eul[3],
                                        const float oldrot[3],
                                        short order,
                                        const float mat[3][3]);
void mat4_normalized_to_compatible_eulO(float eul[3],
                                        const float oldrot[3],
                                        short order,
                                        const float mat[4][4]);
void mat3_to_compatible_eulO(float eul[3],
                             const float oldrot[3],
                             short order,
                             const float mat[3][3]);
void mat4_to_compatible_eulO(float eul[3],
                             const float oldrot[3],
                             short order,
                             const float mat[4][4]);
void quat_to_compatible_eulO(float eul[3],
                             const float oldrot[3],
                             short order,
                             const float quat[4]);
 
void rotate_eulO(float beul[3], short order, char axis, float angle);

 
/* -------------------------------------------------------------------- */
 
void copy_dq_dq(DualQuat *r, const DualQuat *dq);
void normalize_dq(DualQuat *dq, float totweight);
void add_weighted_dq_dq(DualQuat *dq_sum, const DualQuat *dq, float weight);
void add_weighted_dq_dq_pivot(DualQuat *dq_sum,
                              const DualQuat *dq,
                              const float pivot[3],
                              float weight,
                              bool compute_scale_matrix);
void mul_v3m3_dq(float r[3], float R[3][3], DualQuat *dq);
 
void mat4_to_dquat(DualQuat *dq, const float basemat[4][4], const float mat[4][4]);
void dquat_to_mat4(float R[4][4], const DualQuat *dq);

void quat_apply_track(float quat[4], short axis, short upflag);
void vec_apply_track(float vec[3], short axis);

float focallength_to_fov(float focal_length, float sensor);
float fov_to_focallength(float hfov, float sensor);
 
float angle_wrap_rad(float angle);
float angle_wrap_deg(float angle);

float angle_compat_rad(float angle, float angle_compat);

bool mat3_from_axis_conversion(
    int src_forward, int src_up, int dst_forward, int dst_up, float r_mat[3][3]);
bool mat3_from_axis_conversion_single(int src_axis, int dst_axis, float r_mat[3][3]);