kairgo

README

Kairos-SDK-Go

This is the Go wrapper for the Kairos Facial Recognition API. The wrapper was written for Humaniq.co project needs, during the facial image research process.

Contributors

This wrapper was developed by:

• Alexander Kirillov
• Kareem Hepburn

---

Usage

import "github.com/humaniq/kairgo"

Create a new Kairos client, then use the exposed services to access different parts of the Kairos API.

Ported methods:

Authenticate Once

Before you can make API calls you'll need to pass Kairos your credentials App Id and App Key (You only need to do this once). Paste your App Id and App Key into the constructor method like so:

import "github.com/humaniq/kairgo"

const (
  APP_ID  = "kairos_app_id"
  APP_KEY = "kairos_app_key"
)

client, err := kairgo.New("", APP_ID, APP_KEY, nil)

View Your Galleries

This method returns a list of all galleries you've created:

gallery, err := client.ViewGallery("MyGallery")
if err != nil {
  log.Error(err)
  return err
}

// inspect gallery struct

View Your Subjects

This method returns a list of all subjects for a given gallery:

subject, err := client.ViewSubject("MyGallery", "subjectID")
if err != nil {
  log.Error(err)
  return err
}

// inspect subject struct

Remove a Subject

This method removes a subject from given gallery:

subjectRequest := kairgo.RemoveSubjectRequest{
  GalleryName: "MyGallery",
  SubjectID: "subjectID",
}

result, err := client.RemoveSubject(&subjectRequest)

if err != nil {
  log.Error(err)
  return err
}

// Inspect result object for errors, statuses and messages

Remove a Gallery

This method removes a given gallery:

result, err := client.RemoveGallery("MyGallery")
if err != nil {
  log.Error(err)
  return err
}

// inspect result struct

Enroll an Image

The Enroll method registers a face for later recognitions. Here's an example of enrolling a face (subject) using a method that accepts an image URL, and enrolls it as a new subject into your specified gallery:

var (
  imageUrl    = "http://media.kairos.com/kairos-elizabeth.jpg"
  subjectID   = "Elizabeth"
  galleryName = "MyGallery"
)

result, err := client.Enroll(imageUrl, subjectID, galleryName, "", false)
if err != nil {
  log.Error(err)
  return err
}

// Inspect result object

Recognize an Image

The Recognize method takes an image of a subject and attempts to match it against a given gallery of previously-enrolled subjects. Here's an example of recognizing a subject using a method that accepts an image URL, sends it to the API, and returns a match and confidence value:

var (
  imageUrl      = "http://media.kairos.com/kairos-elizabeth.jpg"
  galleryName   = "MyGallery"
  minHeadScale  = ".015"
  threshold     = "0.63"
  maxNumResults = 10
)

result, err := client.Recognize(imageUrl, galleryName, minHeadScale, threshold, maxNumResults)
if err != nil {
  log.Error(err)
  return err
}

// Inspect result object

Detect Image Attributes

The Detect method takes an image of a subject and returns various attributes pertaining to the face features. Here's an example of using detect via method that accepts an image URL, sends it to the API, and returns face attributes:

var (
  detectRequest := kairgo.DetectRequest{
    Image: "http://media.kairos.com/kairos-elizabeth.jpg"
  }
)

result, err := client.Detect(&detectRequest)
if err != nil {
  log.Error(err)
  return err
}

// Inspect result object

Verify image

The Verify method takes an image and verifies that it matches an existing subject in a gallery. Here's an example of using verify via method that accepts a path to an image file, sends it to the API, and returns face attributes:

result, err := client.ViewSubject("MyGallery", "subjectID")
if err != nil {
  log.Error(err)
  return err
}

// Inspect result object

---

Copyrights

All rights belong Kairos support page.

Documentation

Index

• type DetectRequest
  • func (d *DetectRequest) IsValid() (bool, error)
• type Error
• type Kairos
  • func New(api, appID, appKey string, hc httpClient) (*Kairos, error)
  • func (k *Kairos) Detect(detectRequest *DetectRequest) (*ResponseDetect, error)
  • func (k *Kairos) Enroll(image, subjectID, galleryName, minHeadScale string, multipleFaces bool) (*ResponseEnroll, error)
  • func (k *Kairos) ListGalleries() (*ResponseListGalleries, error)
  • func (k *Kairos) Recognize(image, galleryName, minHeadScale, threshold string, maxNumResults int) (*ResponseRecognize, error)
  • func (k *Kairos) RemoveGallery(galleryName string) (*ResponseRemoveGallery, error)
  • func (k *Kairos) RemoveSubject(removeSubjectRequest *RemoveSubjectRequest) (*ResponseRemoveSubject, error)
  • func (k *Kairos) Verify(image, galleryName, subjectID string) (*ResponseVerify, error)
  • func (k *Kairos) ViewGallery(galleryName string) (*ResponseGallery, error)
  • func (k *Kairos) ViewSubject(galleryName, subjectId string) (*ResponseSubject, error)
• type RemoveSubjectRequest
  • func (r *RemoveSubjectRequest) IsValid() (bool, error)
• type ResponseDetect
• type ResponseEnroll
• type ResponseGallery
• type ResponseListGalleries
• type ResponseRecognize
• type ResponseRemoveGallery
• type ResponseRemoveSubject
• type ResponseSubject
• type ResponseVerify

Types

type DetectRequest

type DetectRequest struct {

	// Publicly accessible URL or Base64 encoded photo.
	Image string

	// MinHeadScale defined by you.
	// Is used to set the ratio of the smallest face we should look for in the photo.
	// Accepts a value between .015 (1:64 scale) and .5 (1:2 scale). By default it is set at .015 (1:64 scale) if not specified.
	MinHeadScale float32

	// Selector used to adjust the face detector.
	// If not specified the default of FRONTAL is used.
	// Note that these optional parameters are not reliable for face recognition, but may be useful for face detection uses.
	Selector string
}

DetectRequest

func (*DetectRequest) IsValid

func (d *DetectRequest) IsValid() (bool, error)

type Error

type Error struct {
	Message string `json:"Message"`
	ErrCode int    `json:"ErrCode"`
}

Error ..

type Kairos

type Kairos struct {

	// User agent used when communicating with the Kairos API
	UserAgent string
	// contains filtered or unexported fields
}

Kairos ...

func New

func New(api, appID, appKey string, hc httpClient) (*Kairos, error)

New returns a new Kairos API client.

func (*Kairos) Detect

func (k *Kairos) Detect(detectRequest *DetectRequest) (*ResponseDetect, error)

Detect takes a photo and returns the facial features it finds.

func (*Kairos) Enroll

func (k *Kairos) Enroll(image, subjectID, galleryName, minHeadScale string, multipleFaces bool) (*ResponseEnroll, error)

Enroll takes a photo, finds the faces within it, and stores the faces into a gallery you create.

func (*Kairos) ListGalleries

func (k *Kairos) ListGalleries() (*ResponseListGalleries, error)

ListGalleries lists out all of the galleries you have created.

func (*Kairos) Recognize

func (k *Kairos) Recognize(image, galleryName, minHeadScale, threshold string, maxNumResults int) (*ResponseRecognize, error)

Recognize takes a photo, finds the faces within it, and tries to match them against the faces you have already enrolled into a gallery.

func (*Kairos) RemoveGallery

func (k *Kairos) RemoveGallery(galleryName string) (*ResponseRemoveGallery, error)

RemoveGallery removes a gallery and all of its subjects.

func (*Kairos) RemoveSubject

func (k *Kairos) RemoveSubject(removeSubjectRequest *RemoveSubjectRequest) (*ResponseRemoveSubject, error)

RemoveSubject removes a face you have enrolled within a gallery.

func (*Kairos) Verify

func (k *Kairos) Verify(image, galleryName, subjectID string) (*ResponseVerify, error)

func (*Kairos) ViewGallery

func (k *Kairos) ViewGallery(galleryName string) (*ResponseGallery, error)

ViewGallery lists out all of the faces you have enrolled in a gallery.

func (*Kairos) ViewSubject

func (k *Kairos) ViewSubject(galleryName, subjectId string) (*ResponseSubject, error)

ViewSubject displays all face id's and enrollment timestamps for each template you have enrolled from a given galleryName and subjectId.

galleryName string - Defined by you. Is used to identify the gallery.
subjectId   string - Defined by you. Is used as an identifier for the face.

type RemoveSubjectRequest

type RemoveSubjectRequest struct {
	SubjectID, GalleryName string //required fields
	FaceID                 string //optional fields
}

func (*RemoveSubjectRequest) IsValid

func (r *RemoveSubjectRequest) IsValid() (bool, error)

type ResponseDetect

type ResponseDetect struct {
	RawResponse []byte
	Errors      []Error `json:"Errors"`
	Images      []struct {
		Status string `json:"status"`
		Width  int    `json:"width"`
		Height int    `json:"height"`
		File   string `json:"file"`
		Faces  []struct {
			Face_id         int     `json:"face_id"`
			Quality         float32 `json:"quality"`
			Roll            int     `json:"roll"`
			TopLeftX        int     `json:"topLeftX"`
			TopLeftY        int     `json:"topLeftY"`
			ChinTipX        int     `json:"chinTipX"`
			RightEyeCenterX int     `json:"rightEyeCenterX"`
			Yaw             int     `json:"yaw"`
			ChinTipY        int     `json:"chinTipY"`
			Confidence      float32 `json:"confidence"`
			Height          int     `json:"height"`
			RightEyeCenterY int     `json:"rightEyeCenterY"`
			Width           int     `json:"width"`
			LeftEyeCenterY  int     `json:"leftEyeCenterY"`
			LeftEyeCenterX  int     `json:"leftEyeCenterX"`
			Pitch           int     `json:"pitch"`
			Attributes      struct {
				Lips   string  `json:"lips"`
				Asian  float32 `json:"asian"`
				Gender struct {
					Type string `json:"type"`
				} `json:"gender"`
				Age      int     `json:"age"`
				Hispanic float32 `json:"hispanic"`
				Other    float32 `json:"other"`
				Black    float32 `json:"black"`
				White    float32 `json:"white"`
				Glasses  string  `json:"glasses"`
			} `json:"attributes"`
		} `json:"faces"`
	} `json:"images"`
}

type ResponseEnroll

type ResponseEnroll struct {
	RawResponse []byte
	Errors      []Error `json:"Errors"`
	FaceID      string  `json:"face_id"`
	Images      []struct {
		Attributes struct {
			Lips   string  `json:"lips"`
			Asian  float64 `json:"asian"`
			Gender struct {
				Type string `json:"type"`
			} `json:"gender"`
			Age      int     `json:"age"`
			Hispanic float64 `json:"hispanic"`
			Other    float64 `json:"other"`
			Black    float64 `json:"black"`
			White    float64 `json:"white"`
			Glasses  string  `json:"glasses"`
		} `json:"attributes"`
		Transaction struct {
			Status      string  `json:"status"`
			TopLeftX    int     `json:"topLeftX"`
			TopLeftY    int     `json:"topLeftY"`
			GalleryName string  `json:"gallery_name"`
			Timestamp   string  `json:"timestamp"`
			Height      int     `json:"height"`
			Quality     float64 `json:"quality"`
			Confidence  float64 `json:"confidence"`
			SubjectID   string  `json:"subject_id"`
			Width       int     `json:"width"`
			FaceID      string  `json:"face_id"`
		} `json:"transaction"`
	} `json:"images"`
}

ResponseEnroll ...

type ResponseGallery

type ResponseGallery struct {
	RawResponse []byte
	Errors      []Error  `json:"Errors"`
	Status      string   `json:"status"`
	SubjectIDs  []string `json:"subject_ids"`
}

ResponseGallery ...

type ResponseListGalleries

type ResponseListGalleries struct {
	RawResponse []byte
	Status      string   `json:"status"`
	GalleryIDs  []string `json:"gallery_ids"`
}

type ResponseRecognize

type ResponseRecognize struct {
	Errors      []Error `json:"Errors"`
	RawResponse []byte
	Images      []struct {
		Transaction struct {
			Status      string  `json:"status"`
			Width       int     `json:"width"`
			TopLeftX    int     `json:"topLeftX"`
			TopLeftY    int     `json:"topLeftY"`
			GalleryName string  `json:"gallery_name"`
			FaceID      int     `json:"face_id"`
			Confidence  float64 `json:"confidence"`
			SubjectID   string  `json:"subject_id"`
			Height      int     `json:"height"`
			Quality     float64 `json:"quality"`
		} `json:"transaction"`
		Candidates []struct {
			SubjectID           string  `json:"subject_id"`
			Confidence          float64 `json:"confidence"`
			EnrollmentTimestamp string  `json:"enrollment_timestamp"`
		} `json:"candidates"`
	} `json:"images"`
}

ResponseRecognize ...

type ResponseRemoveGallery

type ResponseRemoveGallery struct {
	RawResponse []byte
	Errors      []Error `json:"Errors"`
	Status      string  `json:"status"`
	Message     string  `json:"message"`
}

type ResponseRemoveSubject

type ResponseRemoveSubject struct {
	RawResponse []byte
	Errors      []Error `json:"Errors"`
	Status      string  `json:"status"`
	Message     string  `json:"message"`
}

type ResponseSubject

type ResponseSubject struct {
	RawResponse []byte
	Errors      []Error `json:"Errors"`
	Status      string  `json:"status"`
	Faces       []struct {
		FaceID       string `json:"face_id"`
		EnrollmentTS string `json:"enrollment_timestamp"`
	} `json:"message"`
}

type ResponseVerify

type ResponseVerify struct {
	RawResponse []byte
	Errors      []Error `json:"Errors"`
	Images      []struct {
		Transaction struct {
			Status      string  `json:"status"`
			Subject_id  string  `json:"subject_id"`
			Quality     float32 `json:"quality"`
			Width       int     `json:"width"`
			Height      int     `json:"height"`
			TopLeftX    int     `json:"topLeftX"`
			TopLeftY    int     `json:"topLeftY"`
			Confidence  float32 `json:"confidence"`
			GalleryName string  `json:"gallery_name"`
		} `json:"transaction"`
	} `json:"images"`
}