IARPA Janus  0.4.0
IARPA Janus Program API
iarpa_janus.h
1 /*******************************************************************************
2  * Copyright (c) 2013 Noblis, Inc.
3  *
4  * Permission is hereby granted, free of charge, to any person obtaining a
5  * copy of this software and/or associated documentation files (the
6  * "Materials"), to deal in the Materials without restriction, including
7  * without limitation the rights to use, copy, modify, merge, publish,
8  * distribute, sublicense, and/or sell copies of the Materials, and to
9  * permit persons to whom the Materials are furnished to do so, subject to
10  * the following conditions:
11  *
12  * The above copyright notice and this permission notice shall be included
13  * in all copies or substantial portions of the Materials.
14  *
15  * THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
18  * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
19  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
20  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
21  * MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
22  ******************************************************************************/
23 
24 #ifndef IARPA_JANUS_H
25 #define IARPA_JANUS_H
26 
27 #include <stdint.h>
28 #include <stdio.h>
29 #include <stdlib.h>
30 
31 #ifdef __cplusplus
32 extern "C" {
33 #endif
34 
103 #if defined JANUS_LIBRARY
104 # if defined _WIN32 || defined __CYGWIN__
105 # define JANUS_EXPORT __declspec(dllexport)
106 # else
107 # define JANUS_EXPORT __attribute__((visibility("default")))
108 # endif
109 #else
110 # if defined _WIN32 || defined __CYGWIN__
111 # define JANUS_EXPORT __declspec(dllimport)
112 # else
113 # define JANUS_EXPORT
114 # endif
115 #endif
116 
117 #define JANUS_VERSION_MAJOR 0
118 #define JANUS_VERSION_MINOR 4
119 #define JANUS_VERSION_PATCH 0
120 
163 typedef enum janus_error
164 {
188 } janus_error;
189 
193 typedef uint8_t janus_data;
194 
198 typedef enum janus_color_space
199 {
203 
225 typedef struct janus_image
226 {
227  janus_data *data;
228  size_t width;
229  size_t height;
230  size_t step;
232 } janus_image;
233 
388 typedef struct janus_attributes
389 {
392  double face_x;
394  double face_y;
396  double face_width;
398  double face_height;
400  double right_eye_x;
402  double right_eye_y;
404  double left_eye_x;
405  double left_eye_y;
406  double nose_base_x;
408  double nose_base_y;
410  double face_yaw;
413  double eyes_visible;
417  double indoor;
418  double gender;
420  double age;
421  double skin_tone;
422  double frame_rate;
424 
464 JANUS_EXPORT janus_error janus_detect(const janus_image image,
465  janus_attributes *attributes_array,
466  const size_t num_requested,
467  size_t *num_actual);
468 
484 JANUS_EXPORT janus_error janus_initialize(const char *sdk_path,
485  const char *temp_path,
486  const char *algorithm);
487 
494 JANUS_EXPORT janus_error janus_finalize();
495 
502 typedef struct janus_template_type *janus_template;
503 
521 JANUS_EXPORT janus_error janus_allocate_template(janus_template *template_);
522 
548 JANUS_EXPORT janus_error janus_augment(const janus_image image,
549  janus_attributes *attributes,
550  janus_template template_);
551 
561  JANUS_EXPORT janus_error janus_free_template(janus_template template_);
562 
571 typedef janus_data *janus_flat_template;
572 
580 JANUS_EXPORT size_t janus_max_template_size();
581 
594 JANUS_EXPORT janus_error janus_flatten_template(const janus_template template_,
595  janus_flat_template
596  flat_template,
597  size_t *bytes);
598 
615 JANUS_EXPORT janus_error janus_verify(const janus_flat_template a,
616  const size_t a_bytes,
617  const janus_flat_template b,
618  const size_t b_bytes,
619  float *similarity);
620 
628 typedef size_t janus_template_id;
629 
637 typedef const char *janus_gallery_path;
638 
656 JANUS_EXPORT janus_error janus_write_gallery(const janus_flat_template
657  *templates,
658  const size_t *templates_bytes,
659  const janus_template_id
660  *template_ids,
661  const size_t num_templates,
662  janus_gallery_path gallery_path);
663 
672 typedef struct janus_gallery_type *janus_gallery;
673 
687 JANUS_EXPORT janus_error janus_open_gallery(janus_gallery_path gallery_path,
688  janus_gallery *gallery);
689 
696  JANUS_EXPORT janus_error janus_close_gallery(janus_gallery gallery);
697 
725 JANUS_EXPORT janus_error janus_search(const janus_flat_template probe,
726  const size_t probe_bytes,
727  const janus_gallery gallery,
728  const size_t num_requested_returns,
729  janus_template_id *template_ids,
730  float *similarities,
731  size_t *num_actual_returns);
732 
768 JANUS_EXPORT janus_error janus_cluster(const janus_gallery gallery,
769  const double hint,
770  janus_template_id *template_ids,
771  int *cluster_ids);
774 #ifdef __cplusplus
775 }
776 #endif
777 
778 #endif /* IARPA_JANUS_H */
janus_data * janus_flat_template
A finalized representation of a template suitable for comparison.
Definition: iarpa_janus.h:571
double face_x
Horizontal offset to top-left corner of face (pixels)
Definition: iarpa_janus.h:392
Definition: iarpa_janus.h:176
janus_data * data
Data buffer.
Definition: iarpa_janus.h:227
JANUS_EXPORT janus_error janus_initialize(const char *sdk_path, const char *temp_path, const char *algorithm)
Call once at the start of the application, before making any other calls to the API.
double detection_confidence
A higher value indicates greater detection confidence.
Definition: iarpa_janus.h:390
double age
Approximate age of subject (years)
Definition: iarpa_janus.h:420
double nose_base_x
Face landmark (pixels)
Definition: iarpa_janus.h:406
Definition: iarpa_janus.h:174
JANUS_EXPORT janus_error janus_augment(const janus_image image, janus_attributes *attributes, janus_template template_)
Add an image to the template.
size_t width
Column count in pixels.
Definition: iarpa_janus.h:228
Definition: iarpa_janus.h:166
struct janus_image janus_image
Common representation for still images and video frames.
JANUS_EXPORT janus_error janus_allocate_template(janus_template *template_)
Allocate memory for an empty template.
const char * janus_gallery_path
Galleries are represented in persistent storage as folders on disk.
Definition: iarpa_janus.h:637
double frame_rate
Frames per second, or 0 for images.
Definition: iarpa_janus.h:422
Definition: iarpa_janus.h:173
struct janus_attributes janus_attributes
Attributes for a particular object in an image.
double face_height
Face vertical size (pixels)
Definition: iarpa_janus.h:398
1 channel grayscale, 8-bit depth.
Definition: iarpa_janus.h:200
janus_color_space
Supported image formats.
Definition: iarpa_janus.h:198
JANUS_EXPORT janus_error janus_detect(const janus_image image, janus_attributes *attributes_array, const size_t num_requested, size_t *num_actual)
Detect objects in a janus_image.
double right_eye_y
Face landmark (pixels)
Definition: iarpa_janus.h:402
double forehead_visible
Visibility of forehead.
Definition: iarpa_janus.h:411
double gender
Gender of subject of interest, 1 for male, 0 for female.
Definition: iarpa_janus.h:418
JANUS_EXPORT janus_error janus_free_template(janus_template template_)
Free memory for a template previously allocated by janus_allocate_template.
double eyes_visible
Visibility of eyes.
Definition: iarpa_janus.h:413
Definition: iarpa_janus.h:165
double face_yaw
Face yaw estimation (degrees).
Definition: iarpa_janus.h:410
JANUS_EXPORT janus_error janus_finalize()
Call once at the end of the application, after making all other calls to the API. ...
Definition: iarpa_janus.h:171
double left_eye_x
Face landmark (pixels)
Definition: iarpa_janus.h:404
JANUS_EXPORT janus_error janus_flatten_template(const janus_template template_, janus_flat_template flat_template, size_t *bytes)
Create a finalized template representation for janus_verify, janus_write_gallery or janus_search...
JANUS_EXPORT janus_error janus_close_gallery(janus_gallery gallery)
Free a gallery previously initialized by janus_open_gallery.
size_t janus_template_id
Unique identifier for a janus_flat_template.
Definition: iarpa_janus.h:628
Definition: iarpa_janus.h:177
JANUS_EXPORT janus_error janus_verify(const janus_flat_template a, const size_t a_bytes, const janus_flat_template b, const size_t b_bytes, float *similarity)
Return a similarity score for two templates.
Attributes for a particular object in an image.
Definition: iarpa_janus.h:388
size_t step
Bytes per row, including padding.
Definition: iarpa_janus.h:230
3 channel color (BGR order), 8-bit depth.
Definition: iarpa_janus.h:201
double face_y
Vertical offset to top-left corner of face (pixels)
Definition: iarpa_janus.h:394
uint8_t janus_data
Data buffer type.
Definition: iarpa_janus.h:193
Definition: iarpa_janus.h:187
Definition: iarpa_janus.h:168
Definition: iarpa_janus.h:172
double left_eye_y
Face landmark (pixels)
Definition: iarpa_janus.h:405
janus_color_space color_space
Arrangement of data.
Definition: iarpa_janus.h:231
Definition: iarpa_janus.h:179
Definition: iarpa_janus.h:167
Definition: iarpa_janus.h:178
double indoor
Image was captured indoors.
Definition: iarpa_janus.h:417
JANUS_EXPORT janus_error janus_write_gallery(const janus_flat_template *templates, const size_t *templates_bytes, const janus_template_id *template_ids, const size_t num_templates, janus_gallery_path gallery_path)
Construct a gallery on disk.
double right_eye_x
Face landmark (pixels)
Definition: iarpa_janus.h:400
Definition: iarpa_janus.h:185
double nose_base_y
Face landmark (pixels)
Definition: iarpa_janus.h:408
Definition: iarpa_janus.h:183
Definition: iarpa_janus.h:170
Common representation for still images and video frames.
Definition: iarpa_janus.h:225
Definition: iarpa_janus.h:181
JANUS_EXPORT janus_error janus_open_gallery(janus_gallery_path gallery_path, janus_gallery *gallery)
Initialize a gallery from a folder created in a previous call to janus_write_gallery.
JANUS_EXPORT janus_error janus_cluster(const janus_gallery gallery, const double hint, janus_template_id *template_ids, int *cluster_ids)
Cluster a gallery into a set of identities.
double face_width
Face horizontal size (pixels)
Definition: iarpa_janus.h:396
double nose_mouth_visible
Visibility of nose and mouth.
Definition: iarpa_janus.h:415
struct janus_gallery_type * janus_gallery
An opaque reference to a read-only janus_gallery_path.
Definition: iarpa_janus.h:672
janus_error
Return type for functions that indicate an error status.
Definition: iarpa_janus.h:163
Definition: iarpa_janus.h:175
double skin_tone
Skin tone of subject.
Definition: iarpa_janus.h:421
struct janus_template_type * janus_template
Contains the recognition information for an object.
Definition: iarpa_janus.h:502
JANUS_EXPORT janus_error janus_search(const janus_flat_template probe, const size_t probe_bytes, const janus_gallery gallery, const size_t num_requested_returns, janus_template_id *template_ids, float *similarities, size_t *num_actual_returns)
Ranked search for a template against a gallery.
JANUS_EXPORT size_t janus_max_template_size()
The maximum size of templates generated by janus_flatten_template.
size_t height
Row count in pixels.
Definition: iarpa_janus.h:229