From b7f035178f62ca6f3d7042cc39ebc9711904f6ac Mon Sep 17 00:00:00 2001 From: maakshishov Date: Tue, 22 Sep 2020 16:02:23 +0300 Subject: [PATCH] Final commit for docs and tests in pimathvector.h --- libs/main/math/pimathvector.h | 437 +++++++++++++++++++++++++++++++++- 1 file changed, 429 insertions(+), 8 deletions(-) diff --git a/libs/main/math/pimathvector.h b/libs/main/math/pimathvector.h index 095b4598..4ea2d8d0 100644 --- a/libs/main/math/pimathvector.h +++ b/libs/main/math/pimathvector.h @@ -52,7 +52,7 @@ public: PIMathVectorT() {resize();} /** - * @brief Constructor that fills a vector "PIMathVectorT" with the values ​​of another vector "PIVector" + * @brief Constructor that fills a vector PIMathVectorT with the values ​​of another vector "PIVector" * * @param val vector of type PIVector which is identified PIMathVectorT * @return vector of type PIMathVectorT with values ​​of vector val @@ -60,9 +60,10 @@ public: PIMathVectorT(const PIVector & val) {resize(); PIMV_FOR(i, 0) c[i] = val[i];} /** - * @brief Constructor that fills a vector "PIMathVectorT" with the subtraction of two vectors + * @brief Constructor that fills a vector PIMathVectorT with the subtraction of two vectors * - * @param st vector of type PIMathVect * @param fn vector of type PIMathVectorT + * @param st vector of type PIMathVectorT + * @param fn vector of type PIMathVectorT * @return vector of type PIMathVectorT with values subtraction vectors "fn" and "st" */ PIMathVectorT(const _CVector & st, const _CVector & fn) {resize(); set(st, fn);} @@ -78,7 +79,7 @@ public: * @brief Method that fills a vector with a value * * @param v value of which the vector is filled - * @return vector of type PIMathVector filled with "v" + * @return vector of type PIMathVectorT filled with "v" */ _CVector & fill(const Type & v) {PIMV_FOR(i, 0) c[i] = v; return *this;} @@ -139,7 +140,8 @@ public: /** * @brief Method that returns the sin of the current vector and vector "v". Works only with vectors which consists of 3 elements * - * @param v vector of type PIMathVectorT * @return sin value of the angle between two vector + * @param v vector of type PIMathVectorT + * @return sin value of the angle between two vector */ Type angleSin(const _CVector & v) const {Type tv = angleCos(v); return sqrt(Type(1) - tv * tv);} @@ -208,7 +210,7 @@ public: /** * @brief Method which checks if every elements of vector are zeros * - * @return true if vector is null, else false + * @return true if vector is zero, else false */ bool isNull() const {PIMV_FOR(i, 0) if (c[i] != Type(0)) return false; return true;} @@ -298,7 +300,7 @@ public: */ void operator *=(const Type & v) {PIMV_FOR(i, 0) c[i] *= v;} - + /** * @brief Multiplication assignment with vector "v" * * @param v vector for the multiplication assigment @@ -430,29 +432,106 @@ private: }; +/** +* @brief Inline operator which returns vector multiplication with value "x" +* +* @param x value for the multiplication +* @param v vector for the multiplication +* @return resulting vector +*/ template inline PIMathVectorT operator *(const Type & x, const PIMathVectorT & v) { return v * x; } +/** +* @brief Inline operator for outputting the vector to the console +* +* @param s PICout type +* @param the vector type PIMathVectorT that we print to the console +* @return PIMathVectorT printed to the console +*/ template inline PICout operator <<(PICout s, const PIMathVectorT & v) {s << "{"; PIMV_FOR(i, 0) {s << v[i]; if (i < Size - 1) s << ", ";} s << "}"; return s;} + +/** +* @brief Inline operator checking if the cross product is zero. Works only with vector containing three elements, otherwise returns current vector +* +* @param f vector of the first operand +* @param s vector of the second operand +* @return true if the cross product is zero, else false +*/ template inline bool operator ||(const PIMathVectorT & f, const PIMathVectorT & s) {return (f * s).isNull();} + +/** +* @brief Inline function which takes the square root of each element in the vector +* +* @param v vector of whose elements the square root is taken +* @return resulting vector +*/ template inline PIMathVectorT sqrt(const PIMathVectorT & v) {PIMathVectorT ret; PIMV_FOR(i, 0) {ret[i] = sqrt(v[i]);} return ret;} + +/** +* @brief Inline function which squares each element of the vector +* +* @param v vector whose elements are squared +* @return resulting vector +*/ template inline PIMathVectorT sqr(const PIMathVectorT & v) {PIMathVectorT ret; PIMV_FOR(i, 0) {ret[i] = sqr(v[i]);} return ret;} +/** +* @brief Inline operator for serializing a vector into a PIByteArray +* +* @param s PIByteArray type +* @param v PIMathVectorT type +* @return PIBiteArray serialized PIMathVectorT +*/ template inline PIByteArray & operator <<(PIByteArray & s, const PIMathVectorT & v) {for (uint i = 0; i < Size; ++i) s << v[i]; return s;} + +/** +* @brief Inline operator to deserialize vector from PIByteArray +* +* @param s PIByteArray type +* @param v PIMathVector type +* @return PIMathVector deserialized from PIByteArray +*/ template inline PIByteArray & operator >>(PIByteArray & s, PIMathVectorT & v) {for (uint i = 0; i < Size; ++i) s >> v[i]; return s;} +/** +* @brief Inline function which returns vector size 2 and type of T +* +* @param x first element of vector +* @param y second element of vector +* @return resulting vector +*/ template inline PIMathVectorT<2u, T> createVectorT2(T x, T y) {return PIMathVectorT<2u, T>(PIVector() << x << y);} + +/** +* @brief Inline function which returns vector size 3 and type of T +* +* @param x first element of vector +* @param y second element of vector +* @param z third element of vector +* @return resulting vector +*/ template inline PIMathVectorT<3u, T> createVectorT3(T x, T y, T z) {return PIMathVectorT<3u, T>(PIVector() << x << y << z);} + +/** +* @brief Inline function which returns vector size 4 and type of T +* +* @param x first element of vector +* @param y second element of vector +* @param z third element of vector +* @param w fouth element of vector +* @return resulting vector +*/ template inline PIMathVectorT<4u, T> createVectorT4(T x, T y, T z, T w) {return PIMathVectorT<4u, T>(PIVector() << x << y << z << w);} @@ -478,69 +557,389 @@ typedef PIMathVectorT<4u, double> PIMathVectorT4d; #define PIMV_FOR(v, s) for (uint v = s; v < c.size(); ++v) +//! \brief A class that works with vector operations, the input data of which is the data type of the vector +//! @tparam Type is the data type of the vector. There are can be basic C++ language data and different classes where the arithmetic operators(=, +=, -=, *=, /=, ==, !=, +, -, *, /) +//! of the C++ language are implemented template class PIP_EXPORT PIMathVector { typedef PIMathVector _CVector; template friend PIByteArray & operator <<(PIByteArray & s, const PIMathVector & v); template friend PIByteArray & operator >>(PIByteArray & s, PIMathVector & v); public: + /** + * @brief Constructor that calls the resize method + * + * @param size vector dimension + * @return resized vector of type PIMathMatrix + */ PIMathVector(const uint size = 0) {c.resize(size);} + + /** + * @brief Constructor that fills a vector PIMathVector with the values ​​of another vector "PIVector" + * + * @param val vector of type PIVector which is identified PIMathVector + * @return vector of type PIMathVector with values ​​of vector val + */ PIMathVector(const PIVector & val) {c.resize(val.size()); PIMV_FOR(i, 0) c[i] = val[i];} + + /** + * @brief Constructor that fills a vector PIMathVector with the subtraction of two vectors + * + * @param st vector of type PIMathVector + * @param fn vector of type PIMathVector + * @return vector of type PIMathVectorT with values subtraction vectors "fn" and "st" + */ PIMathVector(const _CVector & st, const _CVector & fn) {c.resize(st.size()); PIMV_FOR(i, 0) c[i] = fn[i] - st[i];} + /** + * @brief Method which returns size of the vector + * + * @return type uint shows number of elements in this vector + */ uint size() const {return c.size();} + + /** + * @brief Returns self resized vector + * + * @param size new vector dimension + * @param new_value value with which the vector is filled + * @return resized vector + */ _CVector & resize(uint size, const Type & new_value = Type()) {c.resize(size, new_value); return *this;} + + /** + * @brief Returns copy of resized vector + * + * @param size new vector dimension + * @param new_value value with which the vector is filled + * @return resized vector + */ _CVector resized(uint size, const Type & new_value = Type()) {_CVector tv = _CVector(*this); tv.resize(size, new_value); return tv;} + + /** + * @brief Method that fills a vector with a value + * + * @param v value of which the vector is filled + * @return vector of type PIMathVector filled with "v" + */ _CVector & fill(const Type & v) {PIMV_FOR(i, 0) c[i] = v; return *this;} + + /** + * @brief Method that fills a vector with the adittion of vector value and "v" + * + * @param v value of which the vector is filled + * @return vector of type PIMathVector with values adittion of vector value and "v" + */ _CVector & move(const Type & v) {PIMV_FOR(i, 0) c[i] += v; return *this;} + + /** + * @brief Method that fills a vector with the adittion of vector value and "v" + * + * @param v vector of type PIMathVectorT + * @return vector of type PIMathVectorT with values adittion of vector value and "v" + */ _CVector & move(const _CVector & v) {PIMV_FOR(i, 0) c[i] += v[i]; return *this;} + + /** + * @brief Method that replaces two elements in a vector by indices. You cannot use an index larger than the number vector dimension, + * otherwise there will be "undefined behavior" + * + * @param fe index of the first element + * @param se index of the second element + * @return resulting vector of type PIMathVector + */ _CVector & swap(uint fe, uint se) {piSwap(c[fe], c[se]); return *this;} + + /** + * @brief Method that returns sum of the squares of all elements of the vector + * + * @return value equal to the sum of the squares of all elements of the vector + */ Type lengthSqr() const {Type tv(0); PIMV_FOR(i, 0) tv += (c[i] * c[i]); return tv;} + + /** + * @brief Method that returns length of a vector + * + * @return value equal to length of a vector + */ Type length() const {return sqrt(lengthSqr());} + + /** + * @brief Method that returns the sum of the absolute values ​​of all vector values + * + * @return value equal sum of the absolute values ​​of all vector values + */ Type manhattanLength() const {Type tv(0); PIMV_FOR(i, 0) tv += fabs(c[i]); return tv;} + + /** + * @brief Method that returns the cos of the current vector and vector "v" + * + * @param v vector of type PIMathVector + * @return cos value of the angle between two vectors + */ Type angleCos(const _CVector & v) const {Type tv = v.length() * length(); return (tv == Type(0) ? Type(0) : ((*this) ^ v) / tv);} + + /** + * @brief Method that returns the sin of the current vector and vector "v". Works only with vectors which consists of 3 elements + * + * @param v vector of type PIMathVector + * @return sin value of the angle between two vector + */ Type angleSin(const _CVector & v) const {Type tv = angleCos(v); return sqrt(Type(1) - tv * tv);} + + /** + * @brief Method that returns the angle between of the current vector and vector "v" in Rad + * + * @param v vector of type PIMathVector + * @return value of the angle between two vectors in Rad + */ Type angleRad(const _CVector & v) const {return acos(angleCos(v));} + + /** + * @brief Method that returns the angle between of the current vector and vector "v" in Deg + * + * @param v vector of type PIMathVectorT + * @return value of the angle between two vectors in Deg + */ Type angleDeg(const _CVector & v) const {return toDeg(acos(angleCos(v)));} + + /** + * @brief Method that returns a vector equal to the projection of the current vector onto the vector "v" + * + * @param v vector of type PIMathVector + * @return vector of type PIMathVector equal to the projection of the current vector onto the vector "v" + */ _CVector projection(const _CVector & v) {Type tv = v.length(); return (tv == Type(0) ? _CVector() : v * (((*this) ^ v) / tv));} + + /** + * @brief Method that returns a normalized vector + * + * @return copy of normalized vector of type PIMathVector + */ _CVector & normalize() {Type tv = length(); if (tv == Type(1)) return *this; if (piAbs(tv) <= Type(1E-100)) {fill(Type(0)); return *this;} PIMV_FOR(i, 0) c[i] /= tv; return *this;} + + /** + * @brief Method that returns a normalized vector + * + * @return normalized vector of type PIMathVector + */ _CVector normalized() {_CVector tv(*this); tv.normalize(); return tv;} + + /** + * @brief Method which checks if every elements of vector are zeros + * + * @return true if vector is zero, else false + */ bool isNull() const {PIMV_FOR(i, 0) if (c[i] != Type(0)) return false; return true;} + + /** + * @brief Method which checks if vector is valid + * + * @return true if vector is valid, else false + */ bool isValid() const {return !c.isEmpty();} + /** + * @brief Method which checks if current vector is orthogonal to vector "v" + * + * @param v vector of type PIMathVector + * @return true if vectors are orthogonal, else false + */ bool isOrtho(const _CVector & v) const {return ((*this) ^ v) == Type(0);} - const Type & at(uint index) {return c[index];} + /** + * @brief Read-only access to elements reference by index of the vector element "index" + * If you enter an index out of the border of the vector there will be "undefined behavior" + * + * @param index is a parameter that shows the index number of the vector of the selected element + * @return reference to element of vector by index + */ + const Type & at(uint index) {return c[index];} + + /** + * @brief Full access to the element of vector by index. If you enter an index out of the border of the vector there will be "undefined behavior" + * + * @param index is the index of necessary element + * @return element of vector + */ Type & operator [](uint index) {return c[index];} + + /** + * @brief Read-only access to the element of vector by index. If you enter an index out of the border of the vector there will be "undefined behavior" + * + * @param index is the index of necessary element + * @return element of vector + */ Type operator [](uint index) const {return c[index];} + + /** + * @brief Vector assignment to vector "v" of type PIMathVector + * + * @param v vector for the assigment + * @return vector equal to vector "v" + */ _CVector & operator =(const _CVector & v) {c = v.c; return *this;} + + /** + * @brief Vector assignment to value "v" + * + * @param v value for the assigment + * @return vector, each element of which is equal to the value "v" + */ _CVector & operator =(const Type & v) {PIMV_FOR(i, 0) c[i] = v; return *this;} + + /** + * @brief Compare with vector "v" + * + * @param v vector for the compare + * @return if vectors are equal true, else false + */ bool operator ==(const _CVector & v) const {PIMV_FOR(i, 0) if (c[i] != v[i]) return false; return true;} + + /** + * @brief Compare with vector "v" + * + * @param v vector for the compare + * @return if vectors are not equal true, else false + */ bool operator !=(const _CVector & v) const {return !(*this == v);} + + /** + * @brief Addition assignment with vector "v" + * + * @param v vector for the addition assigment + */ void operator +=(const _CVector & v) {PIMV_FOR(i, 0) c[i] += v[i];} + + /** + * @brief Subtraction assignment with vector "v" + * + * @param v vector for the subtraction assigment + */ void operator -=(const _CVector & v) {PIMV_FOR(i, 0) c[i] -= v[i];} + + /** + * @brief Multiplication assignment with value "v" + * + * @param v value for the multiplication assigment + */ void operator *=(const Type & v) {PIMV_FOR(i, 0) c[i] *= v;} + + /** + * @brief Multiplication assignment with vector "v" + * + * @param v vector for the multiplication assigment + */ void operator *=(const _CVector & v) {PIMV_FOR(i, 0) c[i] *= v[i];} + + /** + * @brief Division assignment with value "v" + * + * @param v value for the division assigment + */ void operator /=(const Type & v) {PIMV_FOR(i, 0) c[i] /= v;} + + /** + * @brief Division assignment with vector "v" + * + * @param v vector for the division assigment + */ void operator /=(const _CVector & v) {PIMV_FOR(i, 0) c[i] /= v[i];} + + /** + * @brief Vector substraction + * + * @return the result of vector substraction + */ _CVector operator -() const {_CVector tv; PIMV_FOR(i, 0) tv[i] = -c[i]; return tv;} + + /** + * @brief Matrix addition + * + * @param sm is matrix term + * @return the result of matrix addition + */ _CVector operator +(const _CVector & v) const {_CVector tv = _CVector(*this); PIMV_FOR(i, 0) tv[i] += v[i]; return tv;} + + /** + * @brief Vector substraction + * + * @return the result of vector substraction + */ _CVector operator -(const _CVector & v) const {_CVector tv = _CVector(*this); PIMV_FOR(i, 0) tv[i] -= v[i]; return tv;} + + /** + * @brief Vector multiplication with value "v" + * + * @param v is value factor + * @return the result of vector multiplication + */ _CVector operator *(const Type & v) const {_CVector tv = _CVector(*this); PIMV_FOR(i, 0) tv[i] *= v; return tv;} + + /** + * @brief Vector division with value "v" + * + * @param v is value divider + * @return the result of vector division + */ _CVector operator /(const Type & v) const {_CVector tv = _CVector(*this); PIMV_FOR(i, 0) tv[i] /= v; return tv;} + + /** + * @brief Cross product of two vectors. Works only with vector containing three elements, otherwise returns current vector + * + * @param v is vector for cross product + * @return the result vector equal of cross product + */ _CVector operator *(const _CVector & v) const {if ((c.size() != 3) && (v.size() != 3)) return _CVector(); _CVector tv(3); tv.fill(Type(1)); tv[0] = c[1]*v[2] - v[1]*c[2]; tv[1] = v[0]*c[2] - c[0]*v[2]; tv[2] = c[0]*v[1] - v[0]*c[1]; return tv;} + + /** + * @brief Elementwise assignment of multiplication of two vectors + * + * @param v is vector for multiplication + * @return resulting vector + */ _CVector operator &(const _CVector & v) const {_CVector tv = _CVector(*this); PIMV_FOR(i, 0) tv[i] *= v[i]; return tv;} + + /** + * @brief Absolute value of the dot product + * + * @param v is vector for dot product + * @return resulting vector + */ Type operator ^(const _CVector & v) const {Type tv(0); PIMV_FOR(i, 0) tv += c[i] * v[i]; return tv;} + /** + * @brief Returns the distance between two vectors. Works only for 2-element vectors + * + * @param lp0 is vector + * @param lp1 is vector + * @return resulting value + */ Type distToLine(const _CVector & lp0, const _CVector & lp1) { _CVector a(lp0, lp1), b(lp0, *this), c(lp1, *this); Type f = fabs(a[0]*b[1] - a[1]*b[0]) / a.length(); return f; } + /** + * @brief Converts PIMathVector to PIVector type + * + * @return vector equal PIMathVector but in PIVector type + */ PIVector toVector() const {return c;} + /** + * @brief Returns full access data of vector + * + * @return data of vector + */ inline Type * data() {return c.data();} + + /** + * @brief Returns read-only data of vector + * + * @return data of vector + */ inline const Type * data() const {return c.data();} private: @@ -555,11 +954,33 @@ template inline std::ostream & operator <<(std::ostream & s, const PIMathVector & v) {s << "{"; for (uint i = 0; i < v.size(); ++i) {s << v[i]; if (i < v.size() - 1) s << ", ";} s << "}"; return s;} #endif +/** +* @brief Inline operator for outputting the vector to the console +* +* @param s PICout type +* @param the vector type PIMathVector that we print to the console +* @return PIMathVector printed to the console +*/ template inline PICout operator <<(PICout s, const PIMathVector & v) {s << "Vector{"; for (uint i = 0; i < v.size(); ++i) {s << v[i]; if (i < v.size() - 1) s << ", ";} s << "}"; return s;} +/** +* @brief Inline operator for serializing a vector into a PIByteArray +* +* @param s PIByteArray type +* @param v PIMathVector type +* @return PIBiteArray serialized PIMathVector +*/ template inline PIByteArray & operator <<(PIByteArray & s, const PIMathVector & v) {s << v.c; return s;} + +/** +* @brief Inline operator to deserialize vector from PIByteArray +* +* @param s PIByteArray type +* @param v PIMathVector type +* @return PIMathVector deserialized from PIByteArray +*/ template inline PIByteArray & operator >>(PIByteArray & s, PIMathVector & v) {s >> v.c; return s;}