C++ API Documentation

Refocusing

The saRefocus class can be used to calculate synthetic aperture refocused images after calibration has been performed. It can also be used to calculate refocused images using images rendered via the Scene and Camera classes.

The parse_refocus_settings() function can be used to parse data from a configuration file to populate a refocus_settings variable that can be used to create an saRefocus object.

class saRefocus

Class with functions that allow user to calculate synthetic aperture refocused images using calibration data.

Public Functions

saRefocus(refocus_settings settings)

saRefocus constructor

Parameters

saRefocus(int num_cams, double f)

saRefocus construction to be generally used when rendered data (using Scene and Camera classes is being used

Parameters
  • num_cams: Number of cameras that will be in the simulated array
  • Factor: indicating number of physical units per pixel

void read_calib_data(string path)

Read refractive calibration data.

void read_calib_data_pin(string path)

Read pinhole calibration data.

void read_imgs(string path)

Read images when they are as individual files in separate folders.

void read_imgs_mtiff(string path)

Read images when they are in multipage TIFF files.

Mat refocus(double z, double rx, double ry, double rz, double thresh, int frame)

Calculate a refocused image

Return
Refocused image as OpenCV Mat type
Parameters
  • z: Depth in physical units at which to calculate refocused image
  • rx: Angle by which to rotate focal plane about x axis
  • ry: Angle by which you rotate focal plane about y axis
  • rz: Angle by which to rotate focal plane about z axis
  • thresh: Thresholding level (if additive refocusing is used)
  • frame: The frame (int time) to refocus. Indexing starts at 0.

void GPUliveView()

Start refocusing live view (requires Qt)

void initializeGPU()

Initialize everything required to calculate refocused images on GPU. This is automatically called by GPUliveView() but needs to be explicitly called when live view is not being started.

Particle Localization

The pLocalize class can be used to localize particles in a refocused volume.

class pLocalize

Class with functions that allow a user to find particles in a refocused volume.

Public Functions

pLocalize(localizer_settings s, saRefocus refocus, refocus_settings s2)

pLocalize constructor

Parameters
  • s: A localizer_settings struct variable containing all relevant settings for the localizer
  • refocus: An saRefocus object that has been initialized with data etc.
  • s2: A refocus_settings struct variable. This is the same variable that is passed to the saRefocus class constructor.

vector<Point3f> detected_particles()

Return detected particles

void find_particles_all_frames()

Find particles in all in all frames in the sequence. This is like calling the find_particles_3d() function for each frame.

void find_particles_3d(int frame)

Find particles in the volume. The depth extents between which particles are found are specified in the localizer settings.

Parameters
  • frame: The frame number in which to find the particles.

void write_all_particles_to_file(string path)

Write particles to file

Parameters
  • path: Path of file to write particles to

void write_all_particles(string path)

Write particles to a folder. This is different from the write_all_particles_to_file() function in that this accepts a path to a directory and write particles in a file inside a folder called particles in the path. Note that the path and a folder called particles must exist. The filename is determined automatically based on the relevant settings being used.

Parameters
  • path: Path of folder to write file in. This path must contain another folder called particles in it.

Tracking

The pTracking class can be used to tracking particles detected using pLocalize using a relaxation based scheme as highlighted in [1].

class pTracking

Class with functions to track particles using relaxation based method.

Public Functions

pTracking(string particle_file, double Rn, double Rs)

pTracking constructor

Parameters
  • particle_file: Path of file containing list of particles
  • Rn: Neighborhood threshold
  • Rs: Search threshold

void set_vars(int method, double rn, double rs, double e, double f)

Function to reset relevant variables

Parameters
  • method:
  • rn: Neighborhood threshold
  • rs: Search threshold
  • e: Relaxation set parameter E from [1]
  • f: Relaxation set parameter F from [1]

void track_frames(int start, int end)

Track particles between given frames

Parameters
  • start: Starting frame
  • end: Ending frame

void track_all()

Track particles over all the frames in the input file

void find_long_paths(int l)

Find paths longer than a certain length l in time frames

void find_sized_paths(int l)

Find paths exactly of length l in time frames

void write_tracking_result(string prefix)

Write tracking results to file. The output filename and location is automatically generated based on the path and name of the input particle file passed to the pTracking constructor. For example, if the particle_file is /home/user/project/particles.txt and the prefix string passed is prefix then then tracking results are saved in /home/user/project/particles_prefix_result.txt. The format of this results file is: 

<number of time frames>
<number of matches in frame 1>
<index of particle in frame 1>TAB<index of match particle in frame 2>
<index of particle in frame 1>TAB<index of match particle in frame 2>
...
<number of matches in frame 2>
<index of particle in frame 2>TAB<index of match particle in frame 3>
<index of particle in frame 2>TAB<index of match particle in frame 3>
...
...
where the “\t” between particle indices is a TAB character and the indices are of particles in the particles file used.
Parameters
  • prefix: String of text to add to the output filename

[1] Jia, P., Y. Wang, and Y. Zhang. “Improvement in the independence of relaxation method-based particle tracking velocimetry.” Measurement Science and Technology 24.5 (2013): 055301.

Utility Functions

Here are some utility functions that are part of openFV in order to support miscellaneous functionality that do not really belong to any other class.

Functions in tools.h

void init_logging(int argc, char **argv)

Initialize logging via glog. Should be called at the start of the main() function to enable logging since most output in openFV is routed to the glog library.

void qimshow(Mat image)

Display an image and wait for Esc press

Parameters
  • image: Image to display

vector<double> linspace(double, double, int)

Function to generate a given number of linearly spaced points between specified lower and upper limits

void saveScene(string filename, Scene scn)

Save a Scene object to a binary file

Parameters
  • filename: Name of file to save object to
  • scn: Object of scene class to save

Warning

doxygenfunction: Unable to resolve multiple matches for function “loadScene” with arguments () in doxygen xml output for project “openfv” from directory: xml/. Potential matches: 

- Scene loadScene(string)
- void loadScene(string, Scene&)

Functions in parse_settings.h

void parse_refocus_settings(string filename, refocus_settings &settings, bool help)

Function to parse a refocus settings file and return a refocus_settings variable which can be directly passed to an saRefocus constructor.

Parameters
  • filename: Full path to configuration file
  • settings: Destination refocus_settings variable
  • help: Flag to show all options as a help menu instead of parsing data

Utility Classes

Here are a few classes to support miscellaneous useful functionality.

class fileIO

Class to enable easy writing of data to files.

Public Functions

fileIO(string filename)

Constructor to create a file to write data to. This also checks whether or not the path to the file being created exists or not which determines whether the file is successfully created or not. In case the path is not valid or for some other reason the constructor is unable to create the specified file, all output is routed to a temporary file.

Parameters
  • filename: Name of file to write data to

fileIO &operator<<(int val)

Write int type to file.

fileIO &operator<<(float val)

Write float type to file.

fileIO &operator<<(double val)

Write double type to file.

fileIO &operator<<(string val)

Write a string to the file.

fileIO &operator<<(const char *val)

Write a const char* to file.

fileIO &operator<<(vector<int> val)

Write a vector of int variables to file.

class imageIO
class mtiffReader

Data Types

Here are descriptions of some custom data types defined for internal use within openfv. Most of these are defined in the header typedefs.h.

refocus_settings struct

struct refocus_settings

Settings container passed to saRefocus constructor.

Public Members

int mtiff

Flag indicating if data is in mtiff format files.

int mult

Flag indicating if data is in mp4 videos.

double mult_exp

Multiplicative exponent.

int minlos

Flag to use minLOS (minimum line of sight) reconstruction.

int use_gpu

Flag to use a GPU or not.

int hf_method

Use Homography Fit (HF) method or not.

string calib_file_path

Path to calibration data file.

string images_path

Path to directory where images to be refocused are.

int all_frames

Flag indicating if all frames in the input data should be processed.

int start_frame

Start frame number (used if all_frames is set to 0)

int end_frame

End frame number (used if all_frames is set to 0)

int skip

Successive frames to skip (used if all_frames is set to 0)

vector<int> shifts

Time shift values for each camera.

int resize_images

Flag indicating if calibration images should be resized or not.

double rf

Factor by which to resize calibration images.

int undistort

Whether to undistort images or not.

localizer_settings struct

struct localizer_settings

Settings container passed to pLocalize constructor.

Public Members

int window

Window size to use around a given pixel to search for particle peak

double zmin

Starting z depth of particle search region.

double zmax

Ending z depth of particle search region.

double dz

dz between each successive refocused depth

double thresh

Amount by which to threshold the refocused images.

int zmethod

Method used to calculate the z coordinate of a particle cluster. 1 is for mean z location, 2 is for a quadratic fit (poly2) and 3 is for a gaussian fit.

int cluster_size

Critical cluster size above which to consider a cluster a particle. As of now, regardless of cluster size, a maximum physical z extent of 2.5 mm is used to determine is a detected 2D particle is part of a 3D particle cluster or not.

particle2d struct

struct particle2d

Data type for a particle in 2D. Carries 3D location, average intensity and size in pixels. Used during particle localization.

Public Members

double x

x coordinate of particle

double y

y coordinate of particle

double z

z coordinate of particle

double I

Average intensity of particle.

int size

Size of particle in pixels.

File Formats

Configuration

Utilizes Boost Program Options

A configuration file consists of the assignment of the following variables. Any unassigned variable will hold its corresponding default value.

  • use_gpu (default = 0) 1 to use GPU, 0 for CPU.

  • mult (default = 0) 1 to use the multiplicative method, 0 otherwise.

  • mult_exp (default = .25) Multiplicative method exponent.

  • hf_method (default = 0) 1 to use HF Method, 0 otherwise.

  • mtiff (default = 0) 1 if data is in multipage tiff files.

  • frames (default = “”)

    Array of values in the format start frame, end frame, skip value. No value means all frames are to be processed. frames being one value leads to the processing of that frame alone. Two values indicates the start and end frames with 0 skipped. Three values indicates the start frame, end frame, and skip value.

    Examples:

    omitted – All frames are processed

    frames = 5 : Processes frame 5

    frames = 5,10 : Processes frames 5 through 10, inclusive

    frames = 5,20,4 : Processes frames 5, 10, 15, and 20

  • calib_file_path (default = “”) Path to calibration file, relative to config filepath.

  • images_path (default = “”) Path to data, relative to config filepath.

# can be used for commenting the configuration file

Example configuration file contents:

use_gpu=0
hf_method=1
calib_file_path= ./pinhole_calibration_data/calibration_results/results_000001438970105.txt
images_path= ./pinhole_data/set1_text/

mtiff=0

mult=0
mult_exp=0.5
#frames was omitted to indicate all frames be processed