vpCameraParameters.h

/*
 * ViSP, open source Visual Servoing Platform software.
 * Copyright (C) 2005 - 2024 by Inria. All rights reserved.
 *
 * This software is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * See the file LICENSE.txt at the root directory of this source
 * distribution for additional information about the GNU GPL.
 *
 * For using ViSP with software that can not be combined with the GNU
 * GPL, please contact Inria about acquiring a ViSP Professional
 * Edition License.
 *
 * See https://visp.inria.fr for more information.
 *
 * This software was developed at:
 * Inria Rennes - Bretagne Atlantique
 * Campus Universitaire de Beaulieu
 * 35042 Rennes Cedex
 * France
 *
 * If you have questions regarding the use of this file, please contact
 * Inria at visp@inria.fr
 *
 * This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
 * WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
 *
 * Description:
 * Camera intrinsic parameters.
 */

 
#ifndef VP_CAMERA_PARAMETERS_H
#define VP_CAMERA_PARAMETERS_H
 
#include <iostream>
#include <vector>
 
#include <visp3/core/vpConfig.h>
#include <visp3/core/vpColVector.h>
#include <visp3/core/vpException.h>
#include <visp3/core/vpMatrix.h>
 
#ifdef VISP_HAVE_NLOHMANN_JSON
#include VISP_NLOHMANN_JSON(json.hpp)
#endif
 
BEGIN_VISP_NAMESPACE
 
class VISP_EXPORT vpCameraParameters
{
  friend class vpMeterPixelConversion;
  friend class vpPixelMeterConversion;
 
public:
  typedef enum
  {
    perspectiveProjWithoutDistortion, 
    perspectiveProjWithDistortion,    
    ProjWithKannalaBrandtDistortion   
  } vpCameraParametersProjType;
 
  // generic functions
  vpCameraParameters();
  vpCameraParameters(const vpCameraParameters &c);
  vpCameraParameters(double px, double py, double u0, double v0);
  vpCameraParameters(double px, double py, double u0, double v0, double kud, double kdu);
  vpCameraParameters(double px, double py, double u0, double v0, const std::vector<double> &distortion_coefficients);
 
  vpCameraParameters &operator=(const vpCameraParameters &c);
  bool operator==(const vpCameraParameters &c) const;
  bool operator!=(const vpCameraParameters &c) const;
  virtual ~vpCameraParameters();
 
  void init();
  void init(const vpCameraParameters &c);
  void initFromCalibrationMatrix(const vpMatrix &K);
  void initFromFov(const unsigned int &w, const unsigned int &h, const double &hfov, const double &vfov);
  void initPersProjWithoutDistortion(double px, double py, double u0, double v0);
  void initPersProjWithDistortion(double px, double py, double u0, double v0, double kud, double kdu);
  void initProjWithKannalaBrandtDistortion(double px, double py, double u0, double v0,
    const std::vector<double> &distortion_coefficients);

  inline bool isFovComputed() const { return m_isFov; }
 
  void computeFov(const unsigned int &w, const unsigned int &h);

  inline double getHorizontalFovAngle() const
  {
    if (!m_isFov) {
      std::cout << "Warning: The FOV is not computed, getHorizontalFovAngle() won't be significant." << std::endl;
    }
    return m_hFovAngle;
  }

  inline double getVerticalFovAngle() const
  {
    if (!m_isFov) {
      std::cout << "Warning: The FOV is not computed, getVerticalFovAngle() won't be significant." << std::endl;
    }
    return m_vFovAngle;
  }

  inline std::vector<vpColVector> getFovNormals() const
  {
    if (!m_isFov) {
      std::cout << "Warning: The FOV is not computed, getFovNormals() won't be significant." << std::endl;
    }
    return m_fovNormals;
  }
 
  inline double get_px() const { return m_px; }
  inline double get_px_inverse() const { return m_inv_px; }
  inline double get_py_inverse() const { return m_inv_py; }
  inline double get_py() const { return m_py; }
  inline double get_u0() const { return m_u0; }
  inline double get_v0() const { return m_v0; }
  inline double get_kud() const { return m_kud; }
  inline double get_kdu() const { return m_kdu; }
  inline std::vector<double> getKannalaBrandtDistortionCoefficients() const { return m_dist_coefs; }
 
  inline vpCameraParametersProjType get_projModel() const { return m_projModel; }
 
  vpMatrix get_K() const;
  vpMatrix get_K_inverse() const;
 
  void printParameters();
  friend VISP_EXPORT std::ostream &operator<<(std::ostream &os, const vpCameraParameters &cam);
 
private:
  static const double DEFAULT_U0_PARAMETER;
  static const double DEFAULT_V0_PARAMETER;
  static const double DEFAULT_PX_PARAMETER;
  static const double DEFAULT_PY_PARAMETER;
  static const double DEFAULT_KUD_PARAMETER;
  static const double DEFAULT_KDU_PARAMETER;
  static const vpCameraParametersProjType DEFAULT_PROJ_TYPE;
 
  double m_px, m_py;                     
  double m_u0, m_v0;                     
  double m_kud;                          
  double m_kdu;                          
  std::vector<double> m_dist_coefs;      
 
  unsigned int m_width;                  
  unsigned int m_height;                 
  bool m_isFov;                          
  double m_hFovAngle;                    
  double m_vFovAngle;                    
  std::vector<vpColVector> m_fovNormals; 
 
  double m_inv_px, m_inv_py;
 
  vpCameraParametersProjType m_projModel; 
#ifdef VISP_HAVE_NLOHMANN_JSON
  friend void to_json(nlohmann::json &j, const vpCameraParameters &cam);
  friend void from_json(const nlohmann::json &j, vpCameraParameters &cam);
#endif
};
 
#ifdef VISP_HAVE_NLOHMANN_JSON
 
#if defined(__clang__)
// Mute warning : declaration requires an exit-time destructor [-Wexit-time-destructors]
// message : expanded from macro 'NLOHMANN_JSON_SERIALIZE_ENUM'
#  pragma clang diagnostic push
#  pragma clang diagnostic ignored "-Wexit-time-destructors"
#endif
 
#include VISP_NLOHMANN_JSON(json.hpp)
NLOHMANN_JSON_SERIALIZE_ENUM(vpCameraParameters::vpCameraParametersProjType, {
    {vpCameraParameters::perspectiveProjWithoutDistortion, "perspectiveWithoutDistortion"},
    {vpCameraParameters::perspectiveProjWithDistortion, "perspectiveWithDistortion"},
    {vpCameraParameters::ProjWithKannalaBrandtDistortion, "kannalaBrandtDistortion"}
  });
 
#if defined(__clang__)
#  pragma clang diagnostic pop
#endif

inline void to_json(nlohmann::json &j, const vpCameraParameters &cam)
{
  j["px"] = cam.m_px;
  j["py"] = cam.m_py;
  j["u0"] = cam.m_u0;
  j["v0"] = cam.m_v0;
  j["model"] = cam.m_projModel;
 
  switch (cam.m_projModel) {
  case vpCameraParameters::perspectiveProjWithDistortion:
  {
    j["kud"] = cam.m_kud;
    j["kdu"] = cam.m_kdu;
    break;
  }
  case vpCameraParameters::ProjWithKannalaBrandtDistortion:
  {
    j["dist_coeffs"] = cam.m_dist_coefs;
    break;
  }
  case vpCameraParameters::perspectiveProjWithoutDistortion:
    break;
  default: {
    throw(vpException(vpException::fatalError, "Case not handled in to_json(nlohmann::json &, const vpCameraParameters &)"));
  }
  }
}

inline void from_json(const nlohmann::json &j, vpCameraParameters &cam)
{
  const double px = j.at("px").get<double>();
  const double py = j.at("py").get<double>();
  const double u0 = j.at("u0").get<double>();
  const double v0 = j.at("v0").get<double>();
  const vpCameraParameters::vpCameraParametersProjType model = j.value("model", vpCameraParameters::perspectiveProjWithoutDistortion);
 
  switch (model) {
  case vpCameraParameters::perspectiveProjWithoutDistortion:
  {
    cam.initPersProjWithoutDistortion(px, py, u0, v0);
    break;
  }
  case vpCameraParameters::perspectiveProjWithDistortion:
  {
    const double kud = j.at("kud").get<double>();
    const double kdu = j.at("kdu").get<double>();
    cam.initPersProjWithDistortion(px, py, u0, v0, kud, kdu);
    break;
  }
  case vpCameraParameters::ProjWithKannalaBrandtDistortion:
  {
    const std::vector<double> coeffs = j.at("dist_coeffs").get<std::vector<double>>();
    cam.initProjWithKannalaBrandtDistortion(px, py, u0, v0, coeffs);
    break;
  }
  default: {
    throw(vpException(vpException::fatalError, "Case not handled in from_json(nlohmann::json &, const vpCameraParameters &)"));
  }
  }
}
#endif
END_VISP_NAMESPACE
#endif