+ View the NASA Portal

Search JPL

Search CLARAty

- Algorithms- Infrastructure - Doxygen (public)- Doxygen (private)- Tutorials

- Repository- Nightly Build- Nightly Regression- Feature/Bug Tracking- Build Targets- Procedure- Conventions- Tools

claraty::Tsai_Camera_Model Class Reference
[Data Structure]

#include <tsai_camera_model.h>

Inheritance diagram for claraty::Tsai_Camera_Model:

[legend]Collaboration diagram for claraty::Tsai_Camera_Model:

[legend]List of all members.

Public Member Functions
	Tsai_Camera_Model ()
	Tsai_Camera_Model (int width, int height, const float *projection_matrix, const float *distortion_vector, Frame *frame)
Camera_Model *	clone () const
	~Tsai_Camera_Model ()
void	ray_to_pixel (const Ray &vector, Pixel_Coord &pixel_coord) const
void	pixel_to_ray (const Pixel_Coord &pixel_coord, Ray &vector) const
bool	map_model (Camera_Model &mapped_model, Map_Op &map_op) const
Pixel_Coord	get_mapped_coordinates (Pixel_Coord unmapped_coord) const
Pixel_Coord	get_unmapped_coordinates (Pixel_Coord mapped_coord) const
void	set_distortion_parameters (const Vector< float > &d)
void	set_intrinsic_parameters (const Matrix< float > &p)
const Vector< float > &	get_distortion_parameters () const
const Matrix< float > &	get_intrinsic_parameters () const
void	subsample (int subsampleFactor)
std::string	get_typename () const
bool	io (FDM_Map m)
void	read (std::istream &str)
void	write (std::ostream &str) const
bool	operator== (const Tsai_Camera_Model &rhs) const
bool	operator== (const Camera_Model &rhs) const
void	set_frame (Frame *f)
void	set_name (const std::string &new_name)
virtual const Frame &	get_frame () const
const std::string &	get_name () const
Static Public Member Functions
static Camera_Model *	build ()
static Camera_Model *	build_from_file (const char *filename)
static Camera_Model *	build_from_stream (std::istream &stream)
static Camera_Model *	build_from_typename (const std::string type_name)
Static Public Attributes
static Factory< Camera_Model, std::string > *	factory
Protected Attributes
Frame *	_mounting_frame
std::string	_name
Private Attributes
int	_image_width
int	_image_height
bool	_distorted
Vector< float >	_distortion
Matrix< float >	_intrinsic

---

Detailed Description

The extrinsic parameters are implicitly contained in the frame inherited from the base class. The camera pointing vector is the frame's z unit vector, and the image plane is aligned such that the positive x-pixel direction (normal to the pointing vector) is the frame's x vector, and the positive y-pixel direction is the frame's y vector. Internally the matrix is represented in the canonical form, as

[ fx 0 cx ]
A= [ 0 fy cy ]
[ 0 0 1 ]

with fx, fy the focal length of the system (in horizontal and vertical pixels), and (cx, cy) the pixel coordinates of the central pixel (through the center of projection). When projecting a real-world point of (x, y, z), then, we have to do:

[ row ] [ x ]
p = [ col ] = A * [ y ]
[ w ] [ z ]

p is then in homogeneous coordinates, so the w has to be divided out.

Definition at line 69 of file tsai_camera_model.h.

---

Constructor & Destructor Documentation

claraty::Tsai_Camera_Model::Tsai_Camera_Model

(

)

Definition at line 55 of file tsai_camera_model.cc.

Referenced by clone().

  : _image_width  (0),
    _image_height (0),
    _distorted(false),
    _distortion(4, 0.0F),
    _intrinsic (3, IDENTITY)
{
}

claraty::Tsai_Camera_Model::Tsai_Camera_Model	(	int	width,
		int	height,
		const float *	projection_matrix,
		const float *	distortion_vector,
		Frame *	frame
	)

Definition at line 66 of file tsai_camera_model.cc.

References _distorted, and _distortion.

  : Camera_Model (frame),
    _image_width    (width), 
    _image_height   (height),
    _distorted      (false),
    _distortion     (4, distortion_vector), 
    _intrinsic      (3, 3, projection_matrix)
{
  for (int i = 0; i < 4 && !_distorted; i++)
    if (_distortion(i) != 0)
      _distorted = true;
}

claraty::Tsai_Camera_Model::~Tsai_Camera_Model

(

)

[inline]

Definition at line 87 of file tsai_camera_model.h.

{ }

---

Member Function Documentation

Camera_Model* claraty::Tsai_Camera_Model::clone

(

)

const [inline, virtual]

Implements claraty::Camera_Model.

Definition at line 85 of file tsai_camera_model.h.

References Tsai_Camera_Model().

{ return new Tsai_Camera_Model(*this); }

Here is the call graph for this function:

static Camera_Model* claraty::Tsai_Camera_Model::build

(

)

[inline, static]

Definition at line 89 of file tsai_camera_model.h.

{ return new Tsai_Camera_Model; }

void claraty::Tsai_Camera_Model::ray_to_pixel	(	const Ray &	vector,
		Pixel_Coord &	pixel_coord
	)			const [virtual]

Computes the 2D pixel location in the image from a 3D ray described by the pointing 'vector' with respect to the model's coordinate frame

Implements claraty::Camera_Model.

Definition at line 94 of file tsai_camera_model.cc.

References _distorted, _intrinsic, get_unmapped_coordinates(), and claraty::N_2D_Point< T >::set().

{
  Ray projection = _intrinsic * pointing_direction;

  float c = projection(0) / projection(2);
  float r = projection(1) / projection(2);

  pixel.set(c, r);
 
  if (_distorted) pixel = get_unmapped_coordinates(pixel);
}

Here is the call graph for this function:

void claraty::Tsai_Camera_Model::pixel_to_ray	(	const Pixel_Coord &	pixel,
		Ray &	pointing_direction
	)			const [virtual]

This assumes that the camera model is situated in a frame with the origin at the center of projection, and that the frame is oriented with the z-axis pointing along the optical axis, the x-axis parallel to the x-pixel-axis, and the y-axis parallel to the y-pixel-axis.

Implements claraty::Camera_Model.

Definition at line 116 of file tsai_camera_model.cc.

References _distorted, _intrinsic, get_mapped_coordinates(), claraty::N_2D_Point< T >::get_x(), and claraty::N_2D_Point< T >::get_y().

{ 
  Pixel_Coord mapped_pixel;
  if (_distorted)  // if distorted, find the undistorted / mapped coordinates
    mapped_pixel = get_mapped_coordinates(pixel);
  else
    mapped_pixel = pixel;

  float fx = _intrinsic(0, 0);  // focal length in x-pixels
  float fy = _intrinsic(1, 1);  // focal length in y-pixels
  float cx = _intrinsic(0, 2);  // principal point x coordinate
  float cy = _intrinsic(1, 2);  // principal point y coordinate

  Ray & vec = pointing_direction;

  float rx = mapped_pixel.get_x(), ry = mapped_pixel.get_y();

  vec(0) = (mapped_pixel(0) - cx) / fx;
  vec(1) = (mapped_pixel(1) - cy) / fy;
  vec(2) = 1.0;
  vec /= sqrt(vec(0) * vec(0) + vec(1) * vec(1) + 1); // normalize
}

Here is the call graph for this function:

bool claraty::Tsai_Camera_Model::map_model	(	Camera_Model &	mapped_model,
		Map_Op &	map_op
	)			const [virtual]

This function provides a way for the user to correct models and images for lens distortion. Subclasses should do the right thing to ensure that a reasonable new camera model is built and returned in the mapped_model argument. This should return true if it's possible to build a processed model and mapping op for this model, and false otherwise. Pretty much all subclasses should have a function here that returns true.

Parameters:

[in]	mapped_model	The linearized model.
[in]	map_op	The rectified map.

Returns:

False under all input conditions.

Reimplemented from claraty::Camera_Model.

Definition at line 144 of file tsai_camera_model.cc.

{
/*  rectify.set_camera_model(*this);
  Tsai_Camera_Model *cmm = new Tsai_Camera_Model(*this);
  Vector<float> no_distortion(4, 0.0);
  cmm->set_distortion_parameters(no_distortion);
  linearized_model = cmm;
*/  return true;
}

Pixel_Coord claraty::Tsai_Camera_Model::get_mapped_coordinates

(

Pixel_Coord

unmapped_coord

)

const [virtual]

Inverse operation of the above function. This probably needs to be solved numerically.

Reimplemented from claraty::Camera_Model.

Definition at line 251 of file tsai_camera_model.cc.

References AT_FUNCTION, and claraty::ND_Function_Minimizer::minimize().

Referenced by pixel_to_ray().

{
  double scales  [2] = {0.1, 0.1};
  double solution[2] = {unmapped_coord(0), unmapped_coord(1)};

  Mapped_Pixel_Evaluator eval(*this, unmapped_coord);
  ND_Function_Minimizer  nmm;

  int num_steps = nmm.minimize(solution, scales, 0.001, eval, 2, 100);
  if (num_steps == 0)
    cerr << AT_FUNCTION << "get_undistorted_coordinates failed to converge "
         << unmapped_coord <<" -> " << solution[0] << ", "
         << solution[1] << ")" << endl;
  return Pixel_Coord(solution[0], solution[1]);
}

Here is the call graph for this function:

Pixel_Coord claraty::Tsai_Camera_Model::get_unmapped_coordinates

(

Pixel_Coord

mapped_coord

)

const [virtual]

Most camera models deal with lens distortion by mapping raw images that contain lens distortion to some form of "ideal" images that filter out this distortion. This function maps coordinates from the processed (linearized) image back to the original raw image. For mapping between processed and raw images, subclasses should override this function. Default implementation models no distortion at all. This function provides the inverse mapping of the above function. Lens distortion models are often difficult to invert, and must be inverted numerically. So typically one of these two functions is going significantly more expensive to call than the other. Map_Op assumes that the previous function is low-cost; subclasses should document complexity of both.

Parameters:

[in]

mapped_coord

The (x,y) coordinates of the pixel in the mapped image.

Returns:

The (x,y) pixel coordinates of the original raw (or unrectified) image.

Reimplemented from claraty::Camera_Model.

Definition at line 178 of file tsai_camera_model.cc.

References _distortion, and _intrinsic.

Referenced by claraty::Mapped_Pixel_Evaluator::operator()(), and ray_to_pixel().

{
  // Algorithm from OpenCV.  This is used to create the LUT for rectification,
  // for example by Rectify_Op
  
  // The equations which produce these are:
  // (u, v) = mapped coordinates
  // (u', v') = unmapped (raw) coordinates
  // (x, y) = object coordinates of projected point
  // r2 = x * x + y * y   -- square of distance from object to primary vector
  // k1, k2 are radial distortion parameters; p1, p2 are tangential distortion
  // parameters. principal point is at (cx, cy).

  // u' = u + (u - cx) * (k1 * r2 + k2 * r4 + 2 * p1 * y + p2 * (r2/x + 2x))
  // v' = v + (v - cy) * (k1 * r2 + k2 * r4 + 2 * p2 * x + p1 * (r2/y + 2y))

  // k1 is distortion(0)
  // k2 is distortion(1)
  // p1 is distortion(2)
  // p2 is distortion(3)
  float rx = mapped_coord(0), ry = mapped_coord(1);

  float du = rx - _intrinsic(0, 2);
  float dv = ry - _intrinsic(1, 2);

  float x = du / _intrinsic(0, 0);  // find (x, y) using similar triangles;
  float y = dv / _intrinsic(1, 1);  // assumed z=1.

  float x1 = _distortion(3) / x;
  float y1 = _distortion(2) / y;
  
  float r2 = x * x + y * y;

  float x3 = 2.0 * _distortion(3) * x;
  float y3 = 2.0 * _distortion(2) * y;

  float bx = r2 * (_distortion(0) + r2 * _distortion(1)) + x3 + y3;
  float by = bx + r2 * y1;
  bx += r2 * x1;

  float dx = rx + bx * du;
  float dy = ry + by * dv;
  return Pixel_Coord(dx,dy);
}

void claraty::Tsai_Camera_Model::set_distortion_parameters

(

const Vector< float > &

d

)

Definition at line 271 of file tsai_camera_model.cc.

References _distorted, and _distortion.

{
  _distortion = d;
  _distorted = false;
  if (_distortion != 0) _distorted = true;
}

void claraty::Tsai_Camera_Model::set_intrinsic_parameters

(

const Matrix< float > &

p

)

Definition at line 282 of file tsai_camera_model.cc.

References _intrinsic.

{
  _intrinsic = p;
}

const Vector< float > & claraty::Tsai_Camera_Model::get_distortion_parameters

(

)

const

Definition at line 291 of file tsai_camera_model.cc.

References _distortion.

{
  return _distortion;
}

const Matrix< float > & claraty::Tsai_Camera_Model::get_intrinsic_parameters

(

)

const

Definition at line 300 of file tsai_camera_model.cc.

References _intrinsic.

{
  return _intrinsic;
}

void claraty::Tsai_Camera_Model::subsample

(

int

subsampleFactor

)

[virtual]

Subsample the internal model so that the ray-to-pixel and pixel-to-ray functions work on images subsampled by the same amount. This way image algorithms can work with subsampled images and still have correct camera models to work with. The subsample_factor is a factor; images are sampled to 1/factor, so a factor of 3 means 1/3 the image height & width. Default behavior is to print a warning message and return.

Reimplemented from claraty::Camera_Model.

Definition at line 309 of file tsai_camera_model.cc.

References _distorted, _image_height, _image_width, _intrinsic, and AT_FUNCTION.

{
  if (_distorted) {
    cerr << AT_FUNCTION << "unable to subsample camera models with non-linear"
         << " distortion" << endl;
    return;
  }

  _intrinsic    /= subsampleFactor;
  _image_width  /= subsampleFactor;
  _image_height /= subsampleFactor;
}

std::string claraty::Tsai_Camera_Model::get_typename

(

)

const [inline, virtual]

Implements claraty::Camera_Model.

Definition at line 112 of file tsai_camera_model.h.

{ return "Tsai_Camera_Model"; }

bool claraty::Tsai_Camera_Model::io

(

FDM_Map

m

)

[virtual]

Serializes a camera model.

Parameters:

[in]

m

A map that holds the content of a serialized camera model

Reimplemented from claraty::Camera_Model.

Definition at line 344 of file tsai_camera_model.cc.

References _distorted, _distortion, _intrinsic, claraty::N_2D_Array< T >::begin(), claraty::FDM_Map::field(), claraty::Camera_Model::io(), claraty::FDM_Map::is_read(), and claraty::FDM_Map::peekfield().

{
  bool ok = Camera_Model::io(m);

  const unsigned int latest_version = 2;
  unsigned int thisVersion = latest_version;
  if (m.is_read() && !m.peekfield("version", thisVersion)) {
    // legacy input. We don't write this format anymore, and we never wrote
    // it except for in ascii format, so we have to manually parse it here
    std::string distString, matrixString;

    ok &= m.field("distortion", distString);
    ok &= m.field("matrix", matrixString);
    
    std::istringstream dist(distString);

    for (int i = 0; i < 4; i++)
      dist >> _distortion(i);

    std::istringstream mat(matrixString);
    Matrix<float>::iterator it = _intrinsic.begin();
    for (int i = 0; i < 9; i++, ++it)
      mat >> *it;

    return ok;
  }

  ok &= m.field("version", thisVersion);
  ok &= m.field("distortion", _distortion);
  ok &= m.field("matrix", _intrinsic);

  if (m.is_read()) {
    _distorted = false;
    for (int i = 0; i < 4 && !_distorted; i++)
      if (_distortion(i) != 0)
        _distorted = true;
  }
  return ok;
}

Here is the call graph for this function:

void claraty::Tsai_Camera_Model::read

(

std::istream &

str

)

[virtual]

Reimplemented from claraty::Camera_Model.

void claraty::Tsai_Camera_Model::write

(

std::ostream &

str

)

const [virtual]

Reimplemented from claraty::Camera_Model.

bool claraty::Tsai_Camera_Model::operator==

(

const Tsai_Camera_Model &

rhs

)

const [inline]

Definition at line 119 of file tsai_camera_model.h.

References _distortion, _intrinsic, and claraty::operator==().

                                                      {
    return Camera_Model::operator==(rhs) &&
      _distortion == rhs._distortion &&
      _intrinsic  == rhs._intrinsic;
  }

Here is the call graph for this function:

bool claraty::Camera_Model::operator==

(

const Camera_Model &

rhs

)

const [inherited]

Definition at line 74 of file camera_model.cc.

References claraty::Camera_Model::_mounting_frame, and claraty::Camera_Model::_name.

{
  return _mounting_frame == rhs._mounting_frame && _name == rhs._name;
}

void claraty::Camera_Model::set_frame

(

Frame *

f

)

[inherited]

Assign frame to the camera model

Parameters:

[in]

f

The frame coordinate transformation that defines the mounting of the camera relative to other coordinate frames

Definition at line 99 of file camera_model.cc.

References claraty::Camera_Model::_mounting_frame.

{ 
  _mounting_frame = f; 
}

void claraty::Camera_Model::set_name

(

const std::string &

new_name

)

[inline, inherited]

Definition at line 94 of file camera_model.h.

References claraty::Camera_Model::_name.

{ _name = new_name; }

virtual const Frame& claraty::Camera_Model::get_frame

(

)

const [inline, virtual, inherited]

Definition at line 96 of file camera_model.h.

References claraty::Camera_Model::_mounting_frame.

Referenced by claraty::Stereovision::compute_point_image().

{ return *_mounting_frame; }

const std::string& claraty::Camera_Model::get_name

(

)

const [inline, inherited]

Definition at line 97 of file camera_model.h.

References claraty::Camera_Model::_name.

{ return _name; }

Camera_Model * claraty::Camera_Model::build_from_file

(

const char *

filename

)

[static, inherited]

These are factory wrappers, which load a (subclass of) camera_model from disk. Subclasses have to implement hooks to tie into the factory at startup time.

Definition at line 251 of file camera_model.cc.

References AT_FUNCTION, and claraty::Camera_Model::build_from_stream().

{
  ifstream stream(filename);
  if (!stream) {
    cerr << AT_FUNCTION << " : unable to open file " << filename 
         << " for reading camera model" << endl;
    return NULL;
  }
  return build_from_stream(stream);
}

Here is the call graph for this function:

static Camera_Model* claraty::Camera_Model::build_from_stream

(

std::istream &

stream

)

[static, inherited]

Referenced by claraty::Camera_Model::build_from_file().

static Camera_Model* claraty::Camera_Model::build_from_typename

(

const std::string

type_name

)

[inline, static, inherited]

Definition at line 137 of file camera_model.h.

References claraty::Camera_Model::factory.

Referenced by claraty::io_object().

                                                                       {
    return (*factory)(type_name); 
  }

---

Member Data Documentation

int claraty::Tsai_Camera_Model::_image_width [private]

Definition at line 72 of file tsai_camera_model.h.

Referenced by subsample().

int claraty::Tsai_Camera_Model::_image_height [private]

Definition at line 73 of file tsai_camera_model.h.

Referenced by subsample().

bool claraty::Tsai_Camera_Model::_distorted [private]

Definition at line 74 of file tsai_camera_model.h.

Referenced by io(), pixel_to_ray(), ray_to_pixel(), set_distortion_parameters(), subsample(), and Tsai_Camera_Model().

Vector<float> claraty::Tsai_Camera_Model::_distortion [private]

Definition at line 75 of file tsai_camera_model.h.

Referenced by get_distortion_parameters(), get_unmapped_coordinates(), io(), operator==(), set_distortion_parameters(), and Tsai_Camera_Model().

Matrix<float> claraty::Tsai_Camera_Model::_intrinsic [private]

Definition at line 76 of file tsai_camera_model.h.

Referenced by get_intrinsic_parameters(), get_unmapped_coordinates(), io(), operator==(), pixel_to_ray(), ray_to_pixel(), set_intrinsic_parameters(), and subsample().

Frame* claraty::Camera_Model::_mounting_frame [protected, inherited]

Extrinsic camera parameters

Definition at line 76 of file camera_model.h.

Referenced by claraty::Camera_Model::get_frame(), claraty::Camera_Model::operator=(), claraty::Camera_Model::operator==(), and claraty::Camera_Model::set_frame().

std::string claraty::Camera_Model::_name [protected, inherited]

Definition at line 77 of file camera_model.h.

Referenced by claraty::Camera_Model::get_name(), claraty::Camera_Model::io(), claraty::Camera_Model::operator=(), claraty::Camera_Model::operator==(), and claraty::Camera_Model::set_name().

Factory< Camera_Model, string > * claraty::Camera_Model::factory [static, inherited]

Definition at line 80 of file camera_model.h.

Referenced by claraty::Camera_Model::build_from_typename().

---

The documentation for this class was generated from the following files:

• tsai_camera_model.h
• tsai_camera_model.cc

Last modified: June 05 2007 10:19:53

JPL PRIVACY STATEMENT GLOSSARY SITEMAP FEEDBACK CONTACT US

Site Manager: Issa A.D. Nesnas
Site Maintainer: Kelly Breed
Document Clearance #: CL 07-0635