From 63c68d876157e5d40eef27651e56fa4ac46f37b9 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Picca=20Fr=C3=A9d=C3=A9ric-Emmanuel?= Date: Mon, 22 Feb 2010 14:21:05 +0100 Subject: [PATCH] * add the Hklquaternnion documentation --- Documentation/api/hkl-sections.txt | 6 +- hkl/hkl-axis.c | 7 ++- hkl/hkl-pseudoaxis-common-hkl.c | 2 +- hkl/hkl-pseudoaxis-common-psi.c | 4 +- hkl/hkl-quaternion.c | 124 +++++++++++++++++++++++++++++-------- hkl/hkl-quaternion.h | 63 +++---------------- test/hkl-test-quaternion.c | 22 +++---- 7 files changed, 129 insertions(+), 99 deletions(-) diff --git a/Documentation/api/hkl-sections.txt b/Documentation/api/hkl-sections.txt index 5ee8f2be..b66de421 100644 --- a/Documentation/api/hkl-sections.txt +++ b/Documentation/api/hkl-sections.txt @@ -55,15 +55,15 @@ hkl_detector_factory_new hkl-quaternion HklQuaternion hkl_quaternion_init +hkl_quaternion_init_from_vector +hkl_quaternion_init_from_angle_and_axe hkl_quaternion_fprintf -hkl_quaternion_from_vector -hkl_quaternion_from_angle_and_axe hkl_quaternion_cmp hkl_quaternion_minus_quaternion hkl_quaternion_times_quaternion hkl_quaternion_norm2 hkl_quaternion_conjugate -hkl_quaternion_to_smatrix +hkl_quaternion_to_matrix hkl_quaternion_to_angle_and_axe diff --git a/hkl/hkl-axis.c b/hkl/hkl-axis.c index dcc0b818..1a297480 100644 --- a/hkl/hkl-axis.c +++ b/hkl/hkl-axis.c @@ -33,7 +33,8 @@ /***********/ static void hkl_axis_update(HklAxis *self) { - hkl_quaternion_from_angle_and_axe(&self->q, ((HklParameter *)self)->value, &self->axis_v); + hkl_quaternion_init_from_angle_and_axe(&self->q, + ((HklParameter *)self)->value, &self->axis_v); } /* @@ -234,8 +235,8 @@ void hkl_axis_randomize(HklAxis *self) void hkl_axis_get_quaternion(HklAxis const *self, HklQuaternion *q) { - hkl_quaternion_from_angle_and_axe(q, ((HklParameter *)self)->value, - &self->axis_v); + hkl_quaternion_init_from_angle_and_axe(q, + ((HklParameter *)self)->value, &self->axis_v); } int hkl_axis_is_valid(const HklAxis *self) diff --git a/hkl/hkl-pseudoaxis-common-hkl.c b/hkl/hkl-pseudoaxis-common-hkl.c index 31a9f108..69c9437a 100644 --- a/hkl/hkl-pseudoaxis-common-hkl.c +++ b/hkl/hkl-pseudoaxis-common-hkl.c @@ -99,7 +99,7 @@ int hkl_pseudo_axis_engine_mode_get_hkl_real(HklPseudoAxisEngineMode *self, // R * UB // for now the 0 holder is the sample holder. holder = &geometry->holders[0]; - hkl_quaternion_to_smatrix(&holder->q, &RUB); + hkl_quaternion_to_matrix(&holder->q, &RUB); hkl_matrix_times_matrix(&RUB, &sample->UB); // kf - ki = Q diff --git a/hkl/hkl-pseudoaxis-common-psi.c b/hkl/hkl-pseudoaxis-common-psi.c index 6d21d167..889513aa 100644 --- a/hkl/hkl-pseudoaxis-common-psi.c +++ b/hkl/hkl-pseudoaxis-common-psi.c @@ -67,7 +67,7 @@ static int psi_func(const gsl_vector *x, void *params, gsl_vector *f) // R * UB // for now the 0 holder is the sample holder. holder = &engine->geometry->holders[0]; - hkl_quaternion_to_smatrix(&holder->q, &RUB); + hkl_quaternion_to_matrix(&holder->q, &RUB); hkl_matrix_times_matrix(&RUB, &engine->sample->UB); // compute dhkl0 @@ -132,7 +132,7 @@ static int hkl_pseudo_axis_engine_mode_init_psi_real(HklPseudoAxisEngineMode *ba // R * UB // for now the 0 holder is the sample holder. holder = &geometry->holders[0]; - hkl_quaternion_to_smatrix(&holder->q, &RUB); + hkl_quaternion_to_matrix(&holder->q, &RUB); hkl_matrix_times_matrix(&RUB, &sample->UB); // kf - ki = Q0 diff --git a/hkl/hkl-quaternion.c b/hkl/hkl-quaternion.c index 0b2e4d83..4b1d0d40 100644 --- a/hkl/hkl-quaternion.c +++ b/hkl/hkl-quaternion.c @@ -30,6 +30,16 @@ /* public */ +/** + * hkl_quaternion_init: + * @self: the #HklQuaternion to initialize + * @a: the 1st element value + * @b: the 2nd element value + * @c: the 3rd element value + * @d: the 4th element value + * + * initialize the four elements of an #HklQuaternion + **/ void hkl_quaternion_init(HklQuaternion *self, double a, double b, double c, double d) { @@ -39,7 +49,13 @@ void hkl_quaternion_init(HklQuaternion *self, self->data[3] = d; } -/**print into a file a quaternion */ +/** + * hkl_quaternion_fprintf: + * @file: the file to send the #HklQuaternion into + * @self: the #HklQuaternion to write into the file stream. + * + * print an #HklQuaternion into a FILE stream + **/ void hkl_quaternion_fprintf(FILE *file, HklQuaternion const *self) { double const *Q; @@ -48,15 +64,29 @@ void hkl_quaternion_fprintf(FILE *file, HklQuaternion const *self) fprintf(file, "<%f, %f, %f, %f>", Q[0], Q[1], Q[2], Q[3]); } -/**create an hkl_quaternion from an hkl_vector */ -void hkl_quaternion_from_vector(HklQuaternion *self, HklVector const *v) +/** + * hkl_quaternion_init_from_vector: + * @self: the #HklQuaternion to set + * @v: the #HklVector used to set the self #HklQuaternion + * + * initialize an #HklQuaternion from an #HklVector + **/ +void hkl_quaternion_init_from_vector(HklQuaternion *self, HklVector const *v) { self->data[0] = 0; memcpy(&self->data[1], &v->data[0], sizeof(v->data)); } -inline void hkl_quaternion_from_angle_and_axe(HklQuaternion *self, - double angle, HklVector const *v) +/** + * hkl_quaternion_init_from_angle_and_axe: + * @self: the #HklQuaternion to set + * @angle: the angles of the rotation + * @v: the axe of rotation + * + * initialize an #HklQuaternion from a vector and a angle. + **/ +inline void hkl_quaternion_init_from_angle_and_axe(HklQuaternion *self, + double angle, HklVector const *v) { double norm; double c; @@ -74,19 +104,34 @@ inline void hkl_quaternion_from_angle_and_axe(HklQuaternion *self, self->data[3] = s * v->data[2]; } -/**compare two hkl_quaternions */ -int hkl_quaternion_cmp(HklQuaternion const *self, HklQuaternion const *q1) +/** + * hkl_quaternion_cmp: + * @self: the first #HklQuaternion + * @q: the second #HklQuaternion + * + * compare two #HklQuaternion. + * + * Returns: #HKL_TRUE if both are equal, #HKL_FAIL otherwise. + **/ +int hkl_quaternion_cmp(HklQuaternion const *self, HklQuaternion const *q) { unsigned int i; for (i=0;i<4;i++) - if ( fabs(self->data[i] - q1->data[i]) > HKL_EPSILON ) + if ( fabs(self->data[i] - q->data[i]) > HKL_EPSILON ) return HKL_FALSE; return HKL_TRUE; } -/**@todo test */ -void hkl_quaternion_minus_quaternion(HklQuaternion *self, HklQuaternion const *q) +/** + * hkl_quaternion_minus_quaternion: + * @self: the #HklQuaternion to modify. + * @q: the #HklQuaternion to substract + * + * substract two #HklQuaternions + * Todo: test + **/ +void hkl_quaternion_minus_quaternion(HklQuaternion *self, const HklQuaternion *q) { unsigned int i; @@ -94,7 +139,14 @@ void hkl_quaternion_minus_quaternion(HklQuaternion *self, HklQuaternion const *q self->data[i] -= q->data[i]; } -void hkl_quaternion_times_quaternion(HklQuaternion *self, HklQuaternion const *q) +/** + * hkl_quaternion_times_quaternion: + * @self: the #HklQuaternion to modify + * @q: the #HklQuaternion to multiply by + * + * multiply two quaternions + **/ +void hkl_quaternion_times_quaternion(HklQuaternion *self, const HklQuaternion *q) { HklQuaternion Tmp; double *Q; @@ -115,8 +167,15 @@ void hkl_quaternion_times_quaternion(HklQuaternion *self, HklQuaternion const *q } } -/**compute the norm of a quaternion */ -double hkl_quaternion_norm2(HklQuaternion const *self) +/** + * hkl_quaternion_norm2: + * @self: the quaternion use to compute the norm + * + * compute the norm2 of an #HklQuaternion + * + * Returns: the self #hklquaternion norm + **/ +double hkl_quaternion_norm2(const HklQuaternion *self) { double sum2 = 0; unsigned int i; @@ -125,7 +184,12 @@ double hkl_quaternion_norm2(HklQuaternion const *self) return sqrt(sum2); } -/**compute the conjugate of a quaternion */ +/** + * hkl_quaternion_conjugate: + * @self: the #HklQuaternion to conjugate + * + * compute the conjugate of a quaternion + **/ void hkl_quaternion_conjugate(HklQuaternion *self) { unsigned int i; @@ -134,24 +198,27 @@ void hkl_quaternion_conjugate(HklQuaternion *self) } /** - *@brief Compute the rotation matrix of a Quaternion. - *\return The rotation matrix of a Quaternion. - *\todo optimize + * hkl_quaternion_to_matrix: + * @self: the #HklQuaternion use to compute the #HklMatrix + * @m: the #HklMatrix return. * - *compute the rotation matrix corresponding to the unitary quaternion. - *\f$ q = a + b \cdot i + c \cdot j + d \cdot k \f$ + * Compute the rotation matrix of a Quaternion. * - *\f$ - *\left( + * compute the rotation matrix corresponding to the unitary quaternion. + * \f$ q = a + b \cdot i + c \cdot j + d \cdot k \f$ + * + * \f$ + * \left( * \begin{array}{ccc} * a^2+b^2-c^2-d^2 & 2bc-2ad & 2ac+2bd\\ * 2ad+2bc & a^2-b^2+c^2-d^2 & 2cd-2ab\\ * 2bd-2ac & 2ab+2cd & a^2-b^2-c^2+d^2 * \end{array} - *\right) - *\f$ + * \right) + * \f$ + * Todo: optimize */ -void hkl_quaternion_to_smatrix(HklQuaternion const *self, HklMatrix *m) +void hkl_quaternion_to_matrix(const HklQuaternion *self, HklMatrix *m) { double const *Q; @@ -174,8 +241,13 @@ void hkl_quaternion_to_smatrix(HklQuaternion const *self, HklMatrix *m) } /** - *compute the axe and angle of the unitary quaternion angle [-pi, pi] - *if q is the (1, 0, 0, 0) quaternion return the (0,0,0) axe and a 0 angle + * hkl_quaternion_to_angle_and_axe: + * @self: The #HklQuaternion use to compute the angle and the roation axis. + * @angle: the returned angle of the rotation. + * @v: the returned axis of the rotation. + * + * compute the axe and angle of the unitary quaternion angle [-pi, pi] + * if q is the (1, 0, 0, 0) quaternion return the (0,0,0) axe and a 0 angle */ void hkl_quaternion_to_angle_and_axe(HklQuaternion const *self, double *angle, HklVector *v) diff --git a/hkl/hkl-quaternion.h b/hkl/hkl-quaternion.h index 0e18f7f1..f984d99c 100644 --- a/hkl/hkl-quaternion.h +++ b/hkl/hkl-quaternion.h @@ -38,71 +38,28 @@ struct _HklQuaternion extern void hkl_quaternion_init(HklQuaternion *self, double a, double b, double c, double d); -extern void hkl_quaternion_fprintf(FILE *file, HklQuaternion const *self); +extern void hkl_quaternion_init_from_vector(HklQuaternion *self, const HklVector *v); -/*! - *\brief This constructor creates a quaternion and populates it - *\param v - * - *Create a new quaternion from a vector. - */ -extern void hkl_quaternion_from_vector(HklQuaternion *self, HklVector const *v); +extern void hkl_quaternion_init_from_angle_and_axe(HklQuaternion *self, + double angle, const HklVector *v); -/** - *\brief This constructor creates a quaternion from an angle and a vector - *\param angle the rotation angle. - *\param v the axe of the rotation. - * - * inline to speed the computation. - */ -extern void hkl_quaternion_from_angle_and_axe(HklQuaternion *self, - double angle, HklVector const *v); +extern void hkl_quaternion_fprintf(FILE *file, const HklQuaternion *self); -extern int hkl_quaternion_cmp(HklQuaternion const *self, HklQuaternion const *q); +extern int hkl_quaternion_cmp(const HklQuaternion *self, const HklQuaternion *q); extern void hkl_quaternion_minus_quaternion(HklQuaternion *self, - HklQuaternion const *q); + const HklQuaternion *q); -/** - * @brief multiplication of two quaternions - * - * @param q - * @param q1 - * - * inline to speed the computation. - */ extern void hkl_quaternion_times_quaternion(HklQuaternion *self, - HklQuaternion const *q); + const HklQuaternion *q); -extern double hkl_quaternion_norm2(HklQuaternion const *self); +extern double hkl_quaternion_norm2(const HklQuaternion *self); extern void hkl_quaternion_conjugate(HklQuaternion *self); -/*! - *\brief Compute the rotation matrix of a Quaternion. - *\return The rotation matrix of a Quaternion. - * - *to convert a quaternion to a Matrix: - *\f$ q = a + b \cdot i + c \cdot j + d \cdot k \f$ - * - *\f$ - *\left( - * \begin{array}{ccc} - * a^2+b^2-c^2-d^2 & 2bc-2ad & 2ac+2bd\\ - * 2ad+2bc & a^2-b^2+c^2-d^2 & 2cd-2ab\\ - * 2bd-2ac & 2ab+2cd & a^2-b^2-c^2+d^2 - * \end{array} - *\right) - *\f$ - */ -extern void hkl_quaternion_to_smatrix(HklQuaternion const *self, HklMatrix *m); +extern void hkl_quaternion_to_matrix(const HklQuaternion *self, HklMatrix *m); -/*! - *\brief Decompose a Quaternion into a rotation angle and an Axe of rotation. - *\param[out] angle The angle of the rotation will be strore in this variable. - *\param[out] axe The axe of rotation will be store in this variable. - */ -extern void hkl_quaternion_to_angle_and_axe(HklQuaternion const *self, +extern void hkl_quaternion_to_angle_and_axe(const HklQuaternion *self, double *angle, HklVector *v); HKL_END_DECLS diff --git a/test/hkl-test-quaternion.c b/test/hkl-test-quaternion.c index 84e366bf..a7cf03e5 100644 --- a/test/hkl-test-quaternion.c +++ b/test/hkl-test-quaternion.c @@ -57,29 +57,29 @@ HKL_TEST_SUITE_FUNC(cmp) return HKL_TEST_PASS; } -HKL_TEST_SUITE_FUNC(from_vector) +HKL_TEST_SUITE_FUNC(init_from_vector) { HklQuaternion q_ref = {{0, 1, -1, .5}}; HklVector v = {{1., -1., .5}}; HklQuaternion q; - hkl_quaternion_from_vector(&q, &v); + hkl_quaternion_init_from_vector(&q, &v); HKL_ASSERT_EQUAL(HKL_TRUE, hkl_quaternion_cmp(&q_ref, &q)); return HKL_TEST_PASS; } -HKL_TEST_SUITE_FUNC(from_angle_and_axe) +HKL_TEST_SUITE_FUNC(init_from_angle_and_axe) { HklQuaternion q_ref1 = {{1, 0, 0, 0}}; HklQuaternion q_ref2 = {{sqrt(2.)/2., sqrt(2./9.), -sqrt(2./9.), sqrt(1./18.)}}; HklVector v_ref2 = {{1., -1., .5}}; HklQuaternion q; - hkl_quaternion_from_angle_and_axe(&q, 0, &v_ref2); + hkl_quaternion_init_from_angle_and_axe(&q, 0, &v_ref2); HKL_ASSERT_EQUAL(HKL_TRUE, hkl_quaternion_cmp(&q_ref1, &q)); - hkl_quaternion_from_angle_and_axe(&q, 90. * HKL_DEGTORAD, &v_ref2); + hkl_quaternion_init_from_angle_and_axe(&q, 90. * HKL_DEGTORAD, &v_ref2); HKL_ASSERT_EQUAL(HKL_TRUE, hkl_quaternion_cmp(&q_ref2, &q)); return HKL_TEST_PASS; @@ -116,7 +116,7 @@ HKL_TEST_SUITE_FUNC(conjugate) return HKL_TEST_PASS; } -HKL_TEST_SUITE_FUNC(to_smatrix) +HKL_TEST_SUITE_FUNC(to_matrix) { HklQuaternion q_ref = {{1./sqrt(2), 0, 0, 1./sqrt(2)}}; HklMatrix m_ref = {{{0,-1, 0}, @@ -124,7 +124,7 @@ HKL_TEST_SUITE_FUNC(to_smatrix) {0, 0, 1}}}; HklMatrix m; - hkl_quaternion_to_smatrix(&q_ref, &m); + hkl_quaternion_to_matrix(&q_ref, &m); HKL_ASSERT_EQUAL(HKL_TRUE, hkl_matrix_cmp(&m_ref, &m)); return HKL_TEST_PASS; @@ -151,7 +151,7 @@ HKL_TEST_SUITE_FUNC(to_angle_and_axe) // test other cases for(i=-180; i<180; i++) { angle_ref = i * HKL_DEGTORAD; - hkl_quaternion_from_angle_and_axe(&q, angle_ref, &v_ref); + hkl_quaternion_init_from_angle_and_axe(&q, angle_ref, &v_ref); hkl_quaternion_to_angle_and_axe(&q, &angle, &v); if (!hkl_vector_cmp(&v_ref, &v)) @@ -167,12 +167,12 @@ HKL_TEST_SUITE_BEGIN HKL_TEST( assignment ); HKL_TEST( cmp ); - HKL_TEST( from_vector ); - HKL_TEST( from_angle_and_axe ); + HKL_TEST( init_from_vector ); + HKL_TEST( init_from_angle_and_axe ); HKL_TEST( times_quaternion ); HKL_TEST( norm2 ); HKL_TEST( conjugate ); - HKL_TEST( to_smatrix ); + HKL_TEST( to_matrix ); HKL_TEST( to_angle_and_axe ); HKL_TEST_SUITE_END -- 2.11.4.GIT