Coordinate Systems

From BoofCV
Jump to navigationJump to search

In this page the different standards which BoofCV follows for coordinate systems are specified. Whenever possible the most standard "standard" is used. In some cases there are no standards. If you ever find code inside of BoofCV which does not follow one of these standards please report it.

Array and Matrix Indices

Arrays and matrix coordinates in BoofCV are all zero-indexed (unlike 1-indexed libraries like Matlab), meaning that we start counting from zero instead of one. Some variable names will start at one, i.e. point1, point2. When referencing a coordinate inside of a matrix (row,column) order is employed. For information on the data structures of matrices see EJML.


Pixel Indices

Image pixel coordinates.png

Image pixels are referred in (x,y) order where x is the columns and y is the rows, this is in contrast to matrices which as mentioned above have the reverse order. This is primarily for historical reasons.

As with arrays and matrices, images are zero indexed. The +x axis goes from left to right and the +y axis from top to bottom. The pixel at (0,0) defines the lower-extend and is in the top-left corner of an image. The upper-extent is the bottom-right corner and has the value of (width-1, height-1). The range of values pixel (x,y) occupies is defined as (x,y) inclusive to (x+1,y+1) exclusive. Data is stored in a row-major format.

This is in contrast to Matlab which defines a pixel at (x,y) range to be (x-0.5, y-0.5) to (x+0.5, y+0.5) and is one indexed, i.e. top-left corner is at (1,1).

Spatial Coordinates

Spatial image coordinates are used when using "sub-pixel" coordinates, that is floating point numbers.

Image spatial coordinates.png

The pixel at coordinate (0,0) is defined from (0,0) to (1,1), with (1,1) being exclusive. Stated in more general terms, pixel (i,j) is defined as the integral from (i,j) to (i+1,j+1). Note that the upper extent is exclusive and that (i+1,j+1) is not a member of (i,j) and will belong to pixel coordinate (i+1,j+1).

Unfortunately there is no standard for spatial coordinates and a lot of confusion here across libraries and tools. In Matlab pixel (1,1) is defined from (0.5,0.5) to (1.5,1.5). Please take this in account when doing camera calibration and using a tool in one library then applied it to another library.

Fiducial Marker Coordinate Systems

There is no true standard across all markers, whatever makes the most sense for a specific marker is used. In general the marker's 2D coordinate system will have the origin as the center, +y is up and +x is right. An example is shown below.

Square fiducial parts.png


3-D Coordinate System

Camera coordinates.png

BoofCV uses a right handed coordinate which matches most computer vision systems.

  • +x axis is to the right
  • +y axis is down
  • +z axis is out of the camera