Add example and modify document for class Color

examples/CMakeLists.txt

@@ -24,3 +24,6 @@ target_link_libraries(quaternion_from_euler ignition-math${IGN_MATH_VER}::igniti
 
 add_executable(graph_example graph_example.cc)
 target_link_libraries(graph_example ignition-math${IGN_MATH_VER}::ignition-math${IGN_MATH_VER})
+
+add_executable(color_example color_example.cc)
+target_link_libraries(color_example ignition-math${IGN_MATH_VER}::ignition-math${IGN_MATH_VER})

examples/color_example.cc

@@ -0,0 +1,57 @@
+/*
+ * Copyright (C) 2021 Open Source Robotics Foundation
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+*/
+//! [complete]
+#include <iostream>
+#include <ignition/math/Color.hh>
+
+int main(int argc, char **argv) 
+{
+
+//! [Create a color]
+  ignition::math::Color a = ignition::math::Color(0.3, 0.4, 0.5);
+//! [Create a color]
+  // The channel order is R, G, B, A and the default alpha value of a should be 1.0
+  std::cout << "The alpha value of a should be 1: " << a.A() << std::endl;
+
+
+//! [Set a new color value]
+  a.ignition::math::Color::Set(0.6, 0.7, 0.8, 1.0);
+//! [Set a new color value]
+  std::cout << "The RGBA value of a: " << a << std::endl;
+
+//! [Set value from BGRA]
+  // 0xFF0000FF is blue in BGRA. Convert it to RGBA.
+  ignition::math::Color::BGRA blue = 0xFF0000FF;
+  a.ignition::math::Color::SetFromBGRA(blue);
+//! [Set value from BGRA]
+
+//! [Math operator]
+  std::cout << "Check if a is Blue: " << (a == ignition::math::Color::Blue) << std::endl;
+  std::cout << "The RGB value of a should be (0, 0, 1): " << a[0] << ", " 
+                                                          << a[1] << ", " 
+                                                          << a[2] << std::endl;
+//! [Math operator]
+
+//! [Set value from HSV]
+  // Initialize with HSV. (240, 1.0, 1.0) is blue in HSV.
+  a.ignition::math::Color::SetFromHSV(240.0, 1.0, 1.0);
+  std::cout << "The HSV value of a: " << a.HSV() << std::endl;
+  std::cout << "The RGBA value of a should be (0, 0, 1, 1): " << a << std::endl;
+//! [Set value from HSV]
+
+}
+//! [complete]

include/ignition/math/Color.hh

@@ -34,6 +34,10 @@ namespace ignition
     /// \class Color Color.hh ignition/math/Color.hh
     /// \brief Defines a color using a red (R), green (G), blue (B), and alpha
     /// (A) component. Each color component is in the range [0..1].
+    ///
+    /// ## Example
+    ///
+    /// \snippet examples/color_example.cc complete
     class IGNITION_MATH_VISIBLE Color
     {
       /// \brief (1, 1, 1)
@@ -55,18 +59,38 @@ namespace ignition
 
       /// \typedef RGBA
       /// \brief A RGBA packed value as an unsigned int
+      /// Each 8 bits corresponds to a channel.
+      ///
+      /// \code
+      /// RGBA a = 0xFF0000FF; // (1, 0, 0, 1) for RGBA, i.e. red.
+      /// \endcode
       public: typedef unsigned int RGBA;
 
       /// \typedef BGRA
       /// \brief A BGRA packed value as an unsigned int
+      /// Each 8 bits corresponds to a channel.
+      ///
+      /// \code
+      /// BGRA a = 0xFF0000FF; // (0, 0, 1, 1) for RGBA, i.e. blue.
+      /// \endcode
       public: typedef unsigned int BGRA;
 
       /// \typedef ARGB
       /// \brief A ARGB packed value as an unsigned int
+      /// Each 8 bits corresponds to a channel.
+      ///
+      /// \code
+      /// ARGB a = 0xFF0000FF; // (0, 0, 1, 1) for RGBA, i.e. blue.
+      /// \endcode
       public: typedef unsigned int ARGB;
 
       /// \typedef ABGR
       /// \brief A ABGR packed value as an unsigned int
+      /// Each 8 bits corresponds to a channel.
+      ///
+      /// \code
+      /// ABGR a = 0xFF0000FF; // (1, 0, 0, 1) for RGBA, i.e. red.
+      /// \endcode
       public: typedef unsigned int ABGR;
 
       /// \brief Constructor

tutorials.md.in

@@ -13,6 +13,7 @@ Ignition @IGN_DESIGNATION_CAP@ library and how to use the library effectively.
 4. \subpage angle "Angle example"
 5. \subpage triangle "Triangle example"
 6. \subpage rotation "Rotation example"
+7. \subpage color "Color example"
 
 ## License
 

tutorials/color.md

@@ -0,0 +1,58 @@
+\page color Color example
+
+This tutorial explains how to use the `Color` class from Ignition Math library.
+
+## Compile the code
+
+Go to `ign-math/examples` and use `cmake` to compile the code:
+
+```{.sh}
+git clone https://github.com/ignitionrobotics/ign-math/ -b ign-math6
+cd ign-math/examples
+mkdir build
+cd build
+cmake ..
+make
+```
+
+When the code is compiled, run:
+
+```{.sh}
+./color_example
+```
+
+The ouput of the program:
+
+```{.sh}
+The alpha value of a should be 1: 1
+The RGBA value of a: 0.6 0.7 0.8 1
+Check if a is Blue: 1
+The RGB value of a should be (0, 0, 1): 0, 0, 1
+The HSV value of a: 4 1 1
+The RGBA value of a should be (0, 0, 1, 1): 0 0 1 1
+```
+
+## Code
+
+Create a color with the following RGBA value. The the alpha value is set default to 1.0:
+
+\snippet examples/color_example.cc Create a color
+
+Change the value of a color via `Set()`. All values are set default to 1.0 if not specify.
+
+\snippet examples/color_example.cc Set a new color value
+
+The ABGR, ARGB, BGRA, RGBA are 4 datatypes that allow you to set color from a 32-bit int. Take BGRA as an example:
+
+\snippet examples/color_example.cc Set value from BGRA
+
+Color class overloads math operators including `+`, `-`, `*`, `/`, `[]`, and `==`.
+
+\snippet examples/color_example.cc Math operator
+
+You can also set or read a color in HSV.
+
+\snippet examples/color_example.cc Set value from HSV
+
+There are more functions in `Color`. Take a look at the [API](https://ignitionrobotics.org/api/math/6.9/classignition_1_1math_1_1Color.html)
+