IARPA Janus  0.4.0
IARPA Janus Program API
Classes | Macros | Typedefs | Functions
Janus I/O

Media decoding and evaluation harness. More...

Classes

struct  janus_metric
 A statistic. More...
 
struct  janus_metrics
 All statistics. More...
 

Macros

#define JANUS_ASSERT(EXPRESSION)
 The JANUS_ASSERT macro provides a simple unrecoverable error handling mechanism. More...
 
#define JANUS_CHECK(EXPRESSION)
 The JANUS_CHECK macro provides a simple recoverable error handling mechanism. More...
 

Typedefs

typedef struct janus_video_type * janus_video
 Handle to a private video decoding type.
 
typedef const char * janus_metadata
 File name for a Janus Metadata File. More...
 
typedef const char * janus_matrix
 A dense binary 2D matrix file. More...
 

Functions

JANUS_EXPORT const char * janus_error_to_string (janus_error error)
 janus_error to string. More...
 
JANUS_EXPORT janus_error janus_error_from_string (const char *error)
 janus_error from string. More...
 
JANUS_EXPORT janus_error janus_read_image (const char *file_name, janus_image *image)
 Read an image from disk. More...
 
JANUS_EXPORT void janus_free_image (janus_image image)
 Frees the memory previously allocated for a janus_image. More...
 
JANUS_EXPORT janus_error janus_open_video (const char *file_name, janus_video *video)
 Returns a video ready for reading. More...
 
JANUS_EXPORT janus_error janus_read_frame (janus_video video, janus_image *image)
 Returns the current frame and advances the video to the next frame. More...
 
JANUS_EXPORT void janus_close_video (janus_video video)
 Closes a video previously opened by janus_open_video. More...
 
JANUS_EXPORT janus_error janus_create_template (const char *data_path, janus_metadata metadata, janus_template *template_, janus_template_id *template_id)
 High-level function for enrolling a template from a metadata file. More...
 
JANUS_EXPORT janus_error janus_create_templates (const char *data_path, janus_metadata metadata, const char *gallery_file, int verbose)
 High-level function for enrolling templates from a metadata file and writing templates to disk. More...
 
JANUS_EXPORT janus_error janus_create_gallery (const char *data_path, janus_metadata metadata, janus_gallery_path gallery_path, int verbose)
 High-level function for enrolling a gallery from a metadata file. More...
 
JANUS_EXPORT janus_error janus_write_matrix (void *data, int rows, int columns, int is_mask, janus_metadata target, janus_metadata query, janus_matrix matrix)
 Utility function for creating a janus_matrix. More...
 
JANUS_EXPORT janus_error janus_evaluate_search (janus_gallery_path target, const char *query, janus_metadata target_metadata, janus_metadata query_metadata, janus_matrix simmat, janus_matrix mask, const char *candidate_lists, size_t num_requested_returns)
 Create similarity and mask matricies from two galleries with calls to janus_search. More...
 
JANUS_EXPORT janus_error janus_evaluate_verify (const char *target, const char *query, janus_metadata target_metadata, janus_metadata query_metadata, janus_matrix simmat, janus_matrix mask)
 Create similarity and mask matricies from two galleries with calls to janus_verify. More...
 
JANUS_EXPORT janus_error janus_verify_pairwise (const char *comparisons_file, const char *templates_file, janus_metadata template_metadata, janus_matrix simmat, janus_matrix mask, const char *match_scores)
 High-level function for executing a list of template comparisons. More...
 
JANUS_EXPORT struct janus_metrics janus_get_metrics ()
 Retrieve and reset performance metrics. More...
 
JANUS_EXPORT void janus_print_metrics (struct janus_metrics metrics)
 Print metrics to stdout. More...
 

Detailed Description

Media decoding and evaluation harness.

Macro Definition Documentation

#define JANUS_ASSERT (   EXPRESSION)
Value:
{ \
const janus_error error = (EXPRESSION); \
if (error != JANUS_SUCCESS) { \
fprintf(stderr, "Janus error: %s\n\tFile: %s\n\tLine: %d\n", \
__FILE__, \
__LINE__); \
abort(); \
} \
} \
Definition: iarpa_janus.h:165
janus_error
Return type for functions that indicate an error status.
Definition: iarpa_janus.h:163
JANUS_EXPORT const char * janus_error_to_string(janus_error error)
janus_error to string.

The JANUS_ASSERT macro provides a simple unrecoverable error handling mechanism.

See also
JANUS_CHECK
#define JANUS_CHECK (   EXPRESSION)
Value:
{ \
const janus_error error = (EXPRESSION); \
if (error != JANUS_SUCCESS) \
return error; \
} \
Definition: iarpa_janus.h:165
janus_error
Return type for functions that indicate an error status.
Definition: iarpa_janus.h:163

The JANUS_CHECK macro provides a simple recoverable error handling mechanism.

See also
JANUS_ASSERT

Typedef Documentation

typedef const char* janus_matrix

A dense binary 2D matrix file.

Can be either the similarity or mask matrix format described in MBGC File Overview.

See also
janus_write_matrix janus_evaluate_search janus_evaluate_verify janus_verify_pairwise
typedef const char* janus_metadata

File name for a Janus Metadata File.

A Janus Metadata File is a Comma-Separated Value (CSV) text file with the following format:

TEMPLATE_ID        , SUBJECT_ID, FILE_NAME, MEDIA_ID, FRAME, <janus_attribute>, <janus_attribute>, ..., <janus_attribute>
<janus_template_id>, <int>     , <string> , <int>   , <int>, <double>         , <double>         , ..., <double>
<janus_template_id>, <int>     , <string> , <int>   , <int>, <double>         , <double>         , ..., <double>
...
<janus_template_id>, <int>     , <string> , <int>   , <int>, <double>         , <double>         , ..., <double>

Where:

  • TEMPLATE_ID is a unique integer identifier indicating rows that belong to the same template.
  • SUBJECT_ID is a unique integer identifier used to establish ground truth match/non-match. For the purpose of experimentation, multiple TEMPLATE_ID may have the same SUBJECT_ID.
  • FILE_NAME is a path to the image or video file on disk.
  • MEDIA_ID is a unique integer identifier indicating rows that belong to the same piece of media (image or video clip).
  • FRAME is the video frame number and -1 (or empty string) for still images.
  • All rows associated with the same TEMPLATE_ID occur sequentially.
  • All rows associated with the same TEMPLATE_ID and FILE_NAME occur sequentially ordered by FRAME.
  • A cell is empty when no value is available for the specified attribute.
Examples:

Function Documentation

JANUS_EXPORT void janus_close_video ( janus_video  video)

Closes a video previously opened by janus_open_video.

Call this function to deallocate the memory allocated to decode the video after the desired frames have been read.

Parameters
[in]videoThe video to close.
Remarks
This function is reentrant.
JANUS_EXPORT janus_error janus_create_gallery ( const char *  data_path,
janus_metadata  metadata,
janus_gallery_path  gallery_path,
int  verbose 
)

High-level function for enrolling a gallery from a metadata file.

Parameters
[in]data_pathPrefix path to files in metadata.
[in]metadatajanus_metadata to enroll.
[in]gallery_pathPath to gallery folder.
[in]verbosePrint information and warnings during gallery enrollment.
Remarks
This function is thread_unsafe.
JANUS_EXPORT janus_error janus_create_template ( const char *  data_path,
janus_metadata  metadata,
janus_template template_,
janus_template_id template_id 
)

High-level function for enrolling a template from a metadata file.

Parameters
[in]data_pathPrefix path to files in metadata.
[in]metadatajanus_metadata file to enroll.
[out]template_Constructed template.
[out]template_idTemplate ID from metadata.
Remarks
This function is thread_unsafe.
JANUS_EXPORT janus_error janus_create_templates ( const char *  data_path,
janus_metadata  metadata,
const char *  gallery_file,
int  verbose 
)

High-level function for enrolling templates from a metadata file and writing templates to disk.

Parameters
[in]data_pathPrefix path to files in metadata.
[in]metadatajanus_metadata to enroll.
[in]gallery_fileFile to save the gallery to.
[in]verbosePrint information and warnings during gallery enrollment.
Remarks
This function is thread_unsafe.
JANUS_EXPORT janus_error janus_error_from_string ( const char *  error)

janus_error from string.

Parameters
[in]errorString to decode.
Remarks
This function is thread_safe.
See also
janus_enum
JANUS_EXPORT const char* janus_error_to_string ( janus_error  error)

janus_error to string.

Parameters
[in]errorError code to stringify.
Note
Memory for the return value is static and should not be freed.
Remarks
This function is thread_safe.
JANUS_EXPORT janus_error janus_evaluate_search ( janus_gallery_path  target,
const char *  query,
janus_metadata  target_metadata,
janus_metadata  query_metadata,
janus_matrix  simmat,
janus_matrix  mask,
const char *  candidate_lists,
size_t  num_requested_returns 
)

Create similarity and mask matricies from two galleries with calls to janus_search.

The SUBJECT_ID field is used to determine ground truth match/non-match in the mask. Refer to face.nist.gov for more information on IJB-A and the ".candidate_lists" format.

Parameters
[in]targetPath to gallery being seached against on disk.
[in]queryTemplates file created fron janus_create_templates to constitute the rows for the matrix.
[in]target_metadatametadata file for target.
[in]query_metadatametadata file for query.
[in]simmatSimilarity matrix file to be created.
[in]maskMask matrix file to be created.
[in]candidate_listsText file containing template size and score for each search's requested returns.
[in]num_requested_returnsDesired number of returned results for each call to janus_search.
Remarks
This function is thread_unsafe.
JANUS_EXPORT janus_error janus_evaluate_verify ( const char *  target,
const char *  query,
janus_metadata  target_metadata,
janus_metadata  query_metadata,
janus_matrix  simmat,
janus_matrix  mask 
)

Create similarity and mask matricies from two galleries with calls to janus_verify.

The SUBJECT_ID field is used to determine ground truth match/non-match in the mask.

Parameters
[in]targetTemplates file created from janus_create_templates to constitute the columns of the matrix.
[in]queryTemplates file created from janus_create_templates to constitute the rows for the matrix.
[in]target_metadatametadata file for target.
[in]query_metadatametadata file for query.
[in]simmatSimilarity matrix file to be created.
[in]maskMask matrix file to be created.
Remarks
This function is thread_unsafe.
JANUS_EXPORT void janus_free_image ( janus_image  image)

Frees the memory previously allocated for a janus_image.

Parameters
[in]imagejanus_image to free.
Remarks
This function is reentrant.
See also
janus_allocate_image
JANUS_EXPORT struct janus_metrics janus_get_metrics ( )

Retrieve and reset performance metrics.

Remarks
This function is thread_unsafe.
JANUS_EXPORT janus_error janus_open_video ( const char *  file_name,
janus_video video 
)

Returns a video ready for reading.

Parameters
[in]file_namePath to image file.
[out]videoAddress to store the allocated video.
Remarks
This function is reentrant.
See also
janus_read_frame janus_close_video
JANUS_EXPORT void janus_print_metrics ( struct janus_metrics  metrics)

Print metrics to stdout.

Note
Will only print metrics with count > 0 occurrences.
Remarks
This function is thread_unsafe.
JANUS_EXPORT janus_error janus_read_frame ( janus_video  video,
janus_image image 
)

Returns the current frame and advances the video to the next frame.

Parameters
[in]videoVideo to decode.
[out]imageAddress to store the allocated image.
Remarks
This function is reentrant.
See also
janus_open_video janus_free_image
JANUS_EXPORT janus_error janus_read_image ( const char *  file_name,
janus_image image 
)

Read an image from disk.

Parameters
[in]file_namePath to the image file.
[out]imageAddress to store the decoded image.
Remarks
This function is reentrant.
See also
janus_free_image
JANUS_EXPORT janus_error janus_verify_pairwise ( const char *  comparisons_file,
const char *  templates_file,
janus_metadata  template_metadata,
janus_matrix  simmat,
janus_matrix  mask,
const char *  match_scores 
)

High-level function for executing a list of template comparisons.

Refer to face.nist.gov for more information on IJB-A and the ".matches" format.

Parameters
[in]comparisons_fileFile containing the list of template comparisons to make.
[in]templates_fileTemplates file created from janus_create_templates containing the comparison templates.
[in]template_metadatametadata file for comparison templates.
[in]simmatSimilarity matrix file to be created.
[in]maskMask matrix file to be created.
[in]match_scoresOutput matches file with template size and score recorded for each comparison.
Remarks
This function is thread_unsafe.
JANUS_EXPORT janus_error janus_write_matrix ( void *  data,
int  rows,
int  columns,
int  is_mask,
janus_metadata  target,
janus_metadata  query,
janus_matrix  matrix 
)

Utility function for creating a janus_matrix.

Parameters
[in]dataMatrix data.
[in]rowsMatrix rows.
[in]columnsMatrix columns.
[in]is_maskIf non-zero, data is a uint8_t* of mask values, otherwise data is treated as a float* of similarity values.
[in]targetTarget gallery file name recorded in the matrix header.
[in]queryQuery gallery file name recorded in the matrix header.
[in]matrixFile to write the matrix to.
Remarks
This function is thread_safe.