costmap_2d/include/robot_costmap_2d/observation.h

/*
 * Copyright (c) 2008, 2013, Willow Garage, Inc.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the Willow Garage, Inc. nor the names of its
 *       contributors may be used to endorse or promote products derived from
 *       this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *
 * Authors: Conor McGann
 */

#ifndef ROBOT_COSTMAP_2D_OBSERVATION_H_
#define ROBOT_COSTMAP_2D_OBSERVATION_H_

#include <robot_geometry_msgs/Point.h>
#include <robot_sensor_msgs/PointCloud2.h>
#include <robot_sensor_msgs/DepthCameraData.h>
#include <boost/make_shared.hpp>
#include <boost/shared_ptr.hpp>
#include <utility>

namespace robot_costmap_2d
{

/**
 * @brief A depth frame and its per-source frustum-clearing configuration.
 *
 * The message is shared so returning buffered observations does not copy the
 * full depth image on every costmap update.
 */
/// Per-observation-source configuration of the depth-image frustum clearing,
/// loaded by ObstacleLayer from the source's YAML/ROS params and carried with
/// each DepthCameraObservation.
struct DepthFrustumConfig
{
  unsigned int pixel_step = 0;
  double min_range = 0.0;
  double max_range = 0.0;
  /// 3D clearing rays stop this far [m] before the measured surface.
  /// Negative: legacy 2 * costmap resolution.
  double skip_distance = -1.0;
  /// Full-column clearing from the per-pixel-column nearest in-band return.
  bool column_clearing = false;
  /// Height band [m] used for the in-band test; floor returns below min do
  /// not shorten the beam. max < 0: use the layer max_obstacle_height.
  double column_min_height = 0.10;
  double column_max_height = -1.0;
  /// Column beams stop this far [m] before the nearest in-band return.
  double column_skip_distance = 0.02;
  /// Full columns are only cleared beyond this distance [m]. Negative:
  /// derive each frame from the camera intrinsics and mounting pose.
  double column_cover_distance = -1.0;
  /// Depth-image columns at the LEFT edge excluded from clearing [px]. Covers
  /// the stereo no-disparity strip that is permanently invalid there: those
  /// pixels carry no free-space evidence, so clearing through them erases
  /// obstacles that rotate out of the FOV on that side. Set to the measured
  /// width of the black strip in the raw depth image (a few px margin). 0
  /// disables. Invalid pixels ELSEWHERE still clear (needed for ghost removal).
  unsigned int clear_left_border_px = 0;
  /// Same as clear_left_border_px but for the RIGHT edge, for cameras whose
  /// stereo no-disparity strip sits on the right instead of the left. Measured
  /// from the last image column inward. 0 disables.
  unsigned int clear_right_border_px = 0;
};

class DepthCameraObservation
{
public:
  DepthCameraObservation()
    : data_handle_(),
      data_(nullptr),
      topic_()
  {
  }

  DepthCameraObservation(
      const robot_sensor_msgs::DepthCameraData& data,
      std::string topic,
      const robot::Time& received_time,
      const DepthFrustumConfig& frustum)
    : data_handle_(boost::make_shared<robot_sensor_msgs::DepthCameraData>(data)),
      data_(data_handle_.get()),
      topic_(std::move(topic)),
      received_time_(received_time),
      frustum_(frustum)
  {
  }

  DepthCameraObservation(
      robot_sensor_msgs::DepthCameraData::ConstPtr data,
      std::string topic,
      const robot::Time& received_time,
      const DepthFrustumConfig& frustum)
    : data_handle_(std::move(data)),
      data_(data_handle_.get()),
      topic_(std::move(topic)),
      received_time_(received_time),
      frustum_(frustum)
  {
  }

  DepthCameraObservation(const DepthCameraObservation& other)
    : data_handle_(other.data_handle_),
      data_(data_handle_.get()),
      topic_(other.topic_),
      received_time_(other.received_time_),
      frustum_(other.frustum_)
  {
  }

  DepthCameraObservation(DepthCameraObservation&& other) noexcept
    : data_handle_(std::move(other.data_handle_)),
      data_(data_handle_.get()),
      topic_(std::move(other.topic_)),
      received_time_(other.received_time_),
      frustum_(other.frustum_)
  {
    other.data_ = nullptr;
    other.frustum_ = DepthFrustumConfig();
  }

  DepthCameraObservation& operator=(const DepthCameraObservation& other)
  {
    if (this == &other)
      return *this;

    data_handle_ = other.data_handle_;
    data_ = data_handle_.get();
    topic_ = other.topic_;
    received_time_ = other.received_time_;
    frustum_ = other.frustum_;
    return *this;
  }

  DepthCameraObservation& operator=(DepthCameraObservation&& other) noexcept
  {
    if (this == &other)
      return *this;

    data_handle_ = std::move(other.data_handle_);
    data_ = data_handle_.get();
    topic_ = std::move(other.topic_);
    received_time_ = other.received_time_;
    frustum_ = other.frustum_;

    other.data_ = nullptr;
    other.frustum_ = DepthFrustumConfig();

    return *this;
  }

  ~DepthCameraObservation() = default;

  robot_sensor_msgs::DepthCameraData::ConstPtr data_handle_;
  const robot_sensor_msgs::DepthCameraData* data_;
  std::string topic_;
  robot::Time received_time_;
  DepthFrustumConfig frustum_;
};

/**
 * @brief Stores an observation in terms of a point cloud and the origin of the source
 * @note Tried to make members and constructor arguments const but the compiler would not accept the default
 * assignment operator for vector insertion!
 */
class Observation
{
public:
  /**
   * @brief  Creates an empty observation
   */
  Observation() :
    cloud_handle_(boost::make_shared<robot_sensor_msgs::PointCloud2>()),
    cloud_(cloud_handle_.get()), obstacle_range_(0.0), raytrace_range_(0.0)
  {
  }

  virtual ~Observation() = default;

  /**
   * @brief  Creates an observation from an origin point and a point cloud
   * @param origin The origin point of the observation
   * @param cloud The point cloud of the observation
   * @param obstacle_range The range out to which an observation should be able to insert obstacles
   * @param raytrace_range The range out to which an observation should be able to clear via raytracing
   */
  Observation(robot_geometry_msgs::Point& origin, const robot_sensor_msgs::PointCloud2 &cloud,
              double obstacle_range, double raytrace_range) :
      origin_(origin), cloud_handle_(boost::make_shared<robot_sensor_msgs::PointCloud2>(cloud)),
      cloud_(cloud_handle_.get()),
      obstacle_range_(obstacle_range), raytrace_range_(raytrace_range)
  {
  }

  Observation(robot_geometry_msgs::Point origin,
              boost::shared_ptr<robot_sensor_msgs::PointCloud2> cloud,
              double obstacle_range, double raytrace_range) :
      origin_(std::move(origin)), cloud_handle_(std::move(cloud)),
      cloud_(cloud_handle_.get()),
      obstacle_range_(obstacle_range), raytrace_range_(raytrace_range)
  {
  }

  /**
   * @brief  Copy constructor
   * @param obs The observation to copy
   */
  Observation(const Observation& obs) :
      origin_(obs.origin_), cloud_handle_(obs.cloud_handle_), cloud_(cloud_handle_.get()),
      obstacle_range_(obs.obstacle_range_), raytrace_range_(obs.raytrace_range_)
  {
  }

  Observation(Observation&& obs) noexcept :
      origin_(std::move(obs.origin_)), cloud_handle_(std::move(obs.cloud_handle_)),
      cloud_(cloud_handle_.get()), obstacle_range_(obs.obstacle_range_),
      raytrace_range_(obs.raytrace_range_)
  {
    obs.cloud_ = nullptr;
  }

  Observation& operator=(const Observation& obs)
  {
    if (this == &obs)
      return *this;

    origin_ = obs.origin_;
    cloud_handle_ = obs.cloud_handle_;
    cloud_ = cloud_handle_.get();
    obstacle_range_ = obs.obstacle_range_;
    raytrace_range_ = obs.raytrace_range_;
    return *this;
  }

  Observation& operator=(Observation&& obs) noexcept
  {
    if (this == &obs)
      return *this;

    origin_ = std::move(obs.origin_);
    cloud_handle_ = std::move(obs.cloud_handle_);
    cloud_ = cloud_handle_.get();
    obstacle_range_ = obs.obstacle_range_;
    raytrace_range_ = obs.raytrace_range_;
    obs.cloud_ = nullptr;
    return *this;
  }

  /**
   * @brief  Creates an observation from a point cloud
   * @param cloud The point cloud of the observation
   * @param obstacle_range The range out to which an observation should be able to insert obstacles
   */
  Observation(const robot_sensor_msgs::PointCloud2 &cloud, double obstacle_range) :
      cloud_handle_(boost::make_shared<robot_sensor_msgs::PointCloud2>(cloud)),
      cloud_(cloud_handle_.get()), obstacle_range_(obstacle_range), raytrace_range_(0.0)
  {
  }

  robot_geometry_msgs::Point origin_;
  boost::shared_ptr<robot_sensor_msgs::PointCloud2> cloud_handle_;
  robot_sensor_msgs::PointCloud2* cloud_;
  double obstacle_range_, raytrace_range_;
};

}  // namespace robot_costmap_2d
#endif  // ROBOT_COSTMAP_2D_OBSERVATION_H_