FCam Namespace Reference

Main namespace for the API. More...

Namespaces
namespace	N9
	The namespace for the N9 platform.
Classes
class	Action
	An abstract base class for actions. More...
class	CopyableAction
	For convenience, derived FCam::Action Action classes may inherit from this so they don't have to implement the FCam::Action::copy method. More...
class	AsyncFileWriter
	The AsyncFileWriter saves frames in a low priority background thread. More...
class	AutoFocus
	This class does autofocus, by sweeping the sensor back and forth until a nice thing to focus on is found. More...
struct	Size
	A class to represent sizes of two dimensional objects like images. More...
struct	Rect
	A class to represent rectangles, like regions of an image. More...
class	Device
	An abstract base class for devices. More...
class	EventGenerator
	A base class for things that generate events. More...
class	Event
	An Event marks a change in device state or an error condition. More...
class	Flash
	An abstract base class for camera flashes. More...
struct	_Frame
	A struct containing the data that makes up a Frame. More...
class	Frame
	Data returned by the sensor as a result of a shot. More...
class	HistogramConfig
	The configuration of the histogram generator. More...
class	Histogram
	A histogram returned by the histogram generator. More...
class	Image
	A reference-counted Image object. More...
class	Lens
	An abstract base class for lens devices, to establish a uniform interface to common lens functions. More...
class	Platform
	The abstract base class for static platform data. More...
class	_DNGFrame
	A _Frame struct with added custom fields to encode DNG fields and a DNG thumbnail. More...
class	DNGFrame
	A DNGFrame is constructed by loadDNG, and contains all the metadata found in a DNG file. More...
class	Sensor
	A base class for image sensors. More...
class	SharpnessMapConfig
	The configuration of the sharpness map generator. More...
class	SharpnessMap
	A sharpness map returned by the sharpness map generator. More...
class	Shot
	Shot collects parameters for capturing a frame. More...
class	TagValue
	The values with which a Device can tag a Frame. More...
class	Time
	Time represents a wall clock time. More...
class	TSQueue
	Basic thread-safe consumer/producer queue. More...
Typedefs
typedef std::tr1::unordered_map < std::string, TagValue >	TagMap
	A TagMap is a dictionary mapping strings to TagValues.
Enumerations
enum	ImageFormat {   RGB24 = 0, RGB16, UYVY, YUV24,   RAW, UNKNOWN }
	The various image formats supported by FCam. More...
enum	BayerPattern {   RGGB = 0, BGGR, GRBG, GBRG,   NotBayer }
	The various types of bayer pattern. More...
Functions
void	autoExpose (Shot *s, const Frame &f, float maxGain=32.0f, int maxExposure=125000, float smoothness=0.5)
	Given a shot pointer and a frame, modify the shot parameters to make it better exposed, given the histogram data present in that frame.
void	autoWhiteBalance (Shot *s, const Frame &f, int minWB=3200, int maxWB=7000, float smoothness=0.5)
	Given a shot pointer and a frame, modify the shot parameters to make it better white-balanced, given the histogram data present in that frame.
int	bytesPerPixel (ImageFormat)
	How many bytes per pixel are used by a given format.
bool	getNextEvent (Event *)
	Copies the next pending event into the pointer given.
bool	getNextEvent (Event *, int type)
	Get the next event of a given type.
bool	getNextEvent (Event *, int type, int data)
	Get the next event of a given type and with a specific data field.
bool	getNextEvent (Event *, int type, EventGenerator *creator)
	Get the next event of a given type, created by the specified EventGenerator.
bool	getNextEvent (Event *, int type, int data, EventGenerator *creator)
	Get the next event of a given type, with a specific data field, and created by the specified EventGenerator.
bool	getNextEvent (Event *, EventGenerator *creator)
	Get the next event created by the specified EventGenerator.
void	postEvent (Event)
	Add an event to the event queue.
void	postEvent (int type, int code, const std::string &msg, EventGenerator *creator=NULL)
	A simplified event posting interface that includes a type, integer code, message, and optional creator.
void	error (int code, EventGenerator *creator, const char *fmt,...)
	Post an error event, using printf-style arguments.
void	warning (int code, EventGenerator *creator, const char *fmt,...)
	Post a warning event, using printf-style arguments.
void	error (int code, const char *fmt,...)
	Post an error event with no creator, using printf-style arguments.
void	warning (int code, const char *fmt,...)
	Post a warning event with no creator, using printf-style arguments.
int	version ()
	Returns the minor version number of the FCam library.
int	xyToCCT (float x, float y)
	CIE 1931 x,y to correlated color temperature approximation function.
void	invert3x3 (float *in, float *out)
	Compute a 3x3 matrix inverse.
void	colorMatrixInterpolate (const float *a, const float *b, float alpha, float *result)
	Linearly interpolates two 3x4 color matrices a and b using interpolant alpha.
Image	demosaic (Frame src, float contrast=50.0f, bool denoise=true, int blackLevel=25, float gamma=2.2f)
	Demosaic, white balance, and gamma correct a raw frame, and return a slightly smaller RGB24 format image.
Image	makeThumbnail (Frame src, const Size &thumbSize=Size(640, 480), float contrast=50.0f, int blackLevel=25, float gamma=2.2f)
	Create a low-resolution representation of the input image frame.
void	saveDNG (Frame frame, const std::string &filename)
	Save a DNG file.
DNGFrame	loadDNG (const std::string &filename)
	Load a DNG file.
void	saveDump (Frame frame, std::string filename)
	Save a UYVY, RGB24, or RAW dump file.
Image	loadDump (std::string filename)
	Load a UYVY, RGB24, or RAW dump file.
void	saveJPEG (Frame, std::string filename, int quality=80)
	Save a JPEG file.
void	saveJPEG (Image, std::string filename, int quality=80)
	Save an image as a JPEG file.
Variables
TSQueue< Event >	_eventQueue
	The global event queue.
const float	RGBtoXYZ [9]
	3x3 conversion matrix from linear sRGB to CIE XYZ

---

Detailed Description

Main namespace for the API.

FCam is the main namespace for the API. There are sub-namespaces for each platform. The only sub-namespace supported by this version of the library is N9.

---

Enumeration Type Documentation

enum FCam::ImageFormat

The various image formats supported by FCam.

Enumerator:

RGB24	24 bit per pixel RGB, with 8 bits for each channel
RGB16	16 bit per pixel RGB, broken down into 5 bits for R, 6 for G, and 5 for B
UYVY	16 bit per pixel UYVY. The even numbered bytes alternate between U and V (chrominance), and the odd numbered bytes are Y (luminance). This is usually the best format for blitting to overlays, and is also typically the best format if you just want grayscale data for computer vision applications (in which case, just ignore the even-numbered bytes).
YUV24	24 bit per pixel YUV, with 8 bits for each channels
RAW	16 bit per pixel raw sensor data. Call ::bayerPattern or ::bayerPattern for the correct interpretation. Most sensors are not natively 16-bit, so the high 4-6 bits will commonly be zero (for 12 or 10 bit sensors respectively).
UNKNOWN	An unknown or invalid format. Also acts as a sentinel, so this must be the last entry in the enum.

enum FCam::BayerPattern

The various types of bayer pattern.

Listed as the colors of the top 2x2 block of pixels in scanline order. Non-bayer sensors should return NotBayer.

Enumerator:

RGGB	Red in top left corner.
BGGR	Blue in top left corner.
GRBG	Green in top left corner and first row is green/red.
GBRG	Green in top left corner and first row is green/blue.
NotBayer	Not a bayer-patterned sensor.

---

Function Documentation

void FCam::autoExpose	(	Shot *	s,
		const Frame &	f,
		float	maxGain = 32.0f,
		int	maxExposure = 125000,
		float	smoothness = 0.5
	)

Given a shot pointer and a frame, modify the shot parameters to make it better exposed, given the histogram data present in that frame.

Other parameters are the maximum allowable gain, the maximum allowable exposure, and how smooth changes should be. 0 makes instant changes (and could even oscillate out of control. 1 never changes at all. 0.5 is recommended.

If the algorithm needs to increase brightness, it does so in this order.

• Increase the exposure time up to just less than the frame time of the given shot
• Increase the gain up to the maximum gain
• Increase the exposure time up to the maximum exposure time

If the algorithm needs to decrease brightness, it does so in the reverse order.

void FCam::autoWhiteBalance	(	Shot *	s,
		const Frame &	f,
		int	minWB = 3200,
		int	maxWB = 7000,
		float	smoothness = 0.5
	)

Given a shot pointer and a frame, modify the shot parameters to make it better white-balanced, given the histogram data present in that frame.

Other parameters are the minimum and maximum allowable white balance, and how smooth changes should be. 0 makes instant changes. 1 never changes at all. 0.5 is recommended.

bool FCam::getNextEvent

(

Event *

)

Copies the next pending event into the pointer given.

Returns false if there are no outstanding events. You should periodically process all pending events like so:

FCam::Event event;
while (FCam::getNextEvent(&event)) {
switch(event.type) {
case FCam::Event::Error:
    ...
    break;
case FCam::Event::Warning:
    ...
    break;
case FCam::Event::ShutterPressed:
    ...
    break;
...
default:
    cerr << "Unknown event: " << event.description();
}
}

bool FCam::getNextEvent	(	Event *	,
		int	type
	)

Get the next event of a given type.

Returns false and does not alter the Event argument if no events of that type are currently in the event queue.

bool FCam::getNextEvent	(	Event *	,
		int	type,
		int	data
	)

Get the next event of a given type and with a specific data field.

Returns false and does not alter the Event argument if no matching events are currently in the event queue.

bool FCam::getNextEvent	(	Event *	,
		int	type,
		EventGenerator *	creator
	)

Get the next event of a given type, created by the specified EventGenerator.

Returns false and does not alter the Event argument if no matching events are currently in the event queue.

bool FCam::getNextEvent	(	Event *	,
		int	type,
		int	data,
		EventGenerator *	creator
	)

Get the next event of a given type, with a specific data field, and created by the specified EventGenerator.

Returns false and does not alter the Event argument if no matching events are currently in the event queue.

bool FCam::getNextEvent	(	Event *	,
		EventGenerator *	creator
	)

Get the next event created by the specified EventGenerator.

Returns false and does not alter the Event argument if no matching events are currently in the event queue.

void FCam::postEvent

(

Event

)

Add an event to the event queue.

void FCam::postEvent	(	int	type,
		int	code,
		const std::string &	msg,
		EventGenerator *	creator = NULL
	)

A simplified event posting interface that includes a type, integer code, message, and optional creator.

void FCam::error	(	int	code,
		EventGenerator *	creator,
		const char *	fmt,
			...
	)

Post an error event, using printf-style arguments.

void FCam::warning	(	int	code,
		EventGenerator *	creator,
		const char *	fmt,
			...
	)

Post a warning event, using printf-style arguments.

void FCam::error	(	int	code,
		const char *	fmt,
			...
	)

Post an error event with no creator, using printf-style arguments.

void FCam::warning	(	int	code,
		const char *	fmt,
			...
	)

Post a warning event with no creator, using printf-style arguments.

int FCam::version

(

)

Returns the minor version number of the FCam library.

Currently, possible return values are 0x20 (FCam 1.2.0 running on Harmattan version < PR 1.2) and 0x21 (FCam 1.2.1, running on Harmattan version 1.2)

int FCam::xyToCCT	(	float	x,
		float	y
	)

CIE 1931 x,y to correlated color temperature approximation function.

Uses approximate formula of Hernandez-Andres, et al. 1999: "Calculating correlated color temperatures across the entire gamut of daylight and skylight chromaticities" Accurate within 2% inside 3K-50K CCT.

void FCam::invert3x3	(	float *	in,
		float *	out
	)

Compute a 3x3 matrix inverse.

void FCam::colorMatrixInterpolate	(	const float *	a,
		const float *	b,
		float	alpha,
		float *	result
	)

Linearly interpolates two 3x4 color matrices a and b using interpolant alpha.

(result = a if alpha =0, result = b if alpha = 1). Rescales result matrix to have a minimum row sum of 1.

Image FCam::demosaic	(	Frame	src,
		float	contrast = 50.0f,
		bool	denoise = true,
		int	blackLevel = 25,
		float	gamma = 2.2f
	)

Demosaic, white balance, and gamma correct a raw frame, and return a slightly smaller RGB24 format image.

At least four pixels are lost from each side of the image, more if necessary to maintain the following constraint on the output size: The output will have a width that is a multiple of 40, and a height which is a multiple of 24. In order to color correct, this uses the frame's shot's custom color matrix if it exists. Otherwise, it uses the frame's platform's Platform::rawToRGBColorMatrix method to retrieve the correct white-balanced color conversion matrix.

Image FCam::makeThumbnail	(	Frame	src,
		const Size &	thumbSize = Size(640, 480),
		float	contrast = 50.0f,
		int	blackLevel = 25,
		float	gamma = 2.2f
	)

Create a low-resolution representation of the input image frame.

For a RAW image, this means a fast combined demosaic/downsample and the application of the full post-processing pipeline to create a representative image.

void FCam::saveDNG	(	Frame	frame,
		const std::string &	filename
	)

Save a DNG file.

The frame must have an image in RAW format. All FCam::Frame fields and the tag map are saved in the DNG, along with a thumbnail of the image.

DNGFrame FCam::loadDNG

(

const std::string &

filename

)

Load a DNG file.

Only DNG files saved by FCam are properly supported.

void FCam::saveDump	(	Frame	frame,
		std::string	filename
	)

Save a UYVY, RGB24, or RAW dump file.

For saving uncompressed image data in a very basic image format: Header: 5 4-byte integers representing frames, width, height, channels, and type. Frames will always be 1. Type is either:

• 2 = 8-bit data, such as UYVY or RGB24 data.
• 4 = 16-bit, such as RAW sensor pixel values, in a Bayer mosaic.

Channels will be 3 for RGB24, 2 for UYVY, 1 for RAW data.

Image FCam::loadDump

(

std::string

filename

)

Load a UYVY, RGB24, or RAW dump file.

void FCam::saveJPEG	(	Frame	,
		std::string	filename,
		int	quality = 80
	)

Save a JPEG file.

The frame must have an image in RAW, UYVY, or RGB format. The frame and frame.sensor are queried for all relevant data to put in the EXIF tags. You can also pass in a jpeg quality level between 0 and 100.

void FCam::saveJPEG	(	Image	,
		std::string	filename,
		int	quality = 80
	)

Save an image as a JPEG file.

The image must be in UYVY or RGB format. No EXIF tags are saved. You can also pass in a jpeg quality level between 0 and 100.