Rename Classify to Identify/IdentifyMultiples; add sentinel errors

Aligns with go-face's Identify/IdentifyThreshold rename (breaking, no
alias) and biometric terminology (Detect -> Recognize -> Compare ->
Identify).

Also replaces string-matched error messages with exported sentinel
errors (ErrNoFace, ErrNotSingleFace, ErrNoMatch, ErrDatasetFileNotFound)
checkable via errors.Is, and fixes a stale doc comment on Identify that
claimed it returns an empty list on no match (it returns ErrNoMatch).

Requires go-face v1.1.0.

Author: Leandro

README.md

@@ -3,7 +3,7 @@
 Face detection and recognition for Go, built on top of [dlib](http://dlib.net)
 via [go-face](https://github.com/leandroveronezi/go-face). It wraps the
 lower-level go-face API into a small, batteries-included `Recognizer` type:
-load a photo, find faces, classify them against a labeled dataset, and draw
+load a photo, find faces, identify them against a labeled dataset, and draw
 the results back onto the image — in a handful of method calls.
 
 [![CI](https://github.com/leandroveronezi/go-recognizer/actions/workflows/ci.yml/badge.svg)](https://github.com/leandroveronezi/go-recognizer/actions/workflows/ci.yml)
@@ -15,10 +15,10 @@ the results back onto the image — in a handful of method calls.
 ## Features
 
 - **Detection** — find one or many faces in an image, sorted left to right.
-- **Recognition** — classify detected faces against a dataset of known people.
-- **Incremental dataset updates** — `AddImageToDataset` keeps the classifier in
+- **Recognition** — identify detected faces against a dataset of known people.
+- **Incremental dataset updates** — `AddImageToDataset` keeps the identifier in
   sync as each face is added; no need to rebuild the whole sample set.
-- **Match distance/confidence** — `Classify`/`ClassifyMultiples` return the
+- **Match distance/confidence** — `Identify`/`IdentifyMultiples` return the
   matched face's `Distance` and a normalized `Confidence` score, not just an ID.
 - **Landmarks** — detected faces carry their `Shapes` (facial landmark
   points). Defaults to 5 points (eye corners, nose base); set
@@ -40,6 +40,10 @@ the results back onto the image — in a handful of method calls.
 - **Dataset persistence** — save/load known faces to/from a JSON file.
 - **Drawing helpers** — annotate the source image with boxes, labels, and
   landmark points for the faces found.
+- **Typed errors** — `AddImageToDataset`/`RecognizeSingle`/`Identify`/
+  `LoadDataset` return sentinel errors (`ErrNoFace`, `ErrNotSingleFace`,
+  `ErrNoMatch`, `ErrDatasetFileNotFound`) checkable with `errors.Is`,
+  instead of matching on error text. See [Errors](#errors) below.
 
 ## Requirements
 
@@ -244,9 +248,9 @@ func main() {
 	addFile(&rec, filepath.Join(fotosDir, "leonard.jpg"), "Leonard")
 
 	// No rec.SetSamples() call needed here: AddImageToDataset already
-	// keeps the classifier in sync incrementally as each face is added.
+	// keeps the identifier in sync incrementally as each face is added.
 
-	faces, err := rec.ClassifyMultiples(filepath.Join(fotosDir, "elenco3.jpg"))
+	faces, err := rec.IdentifyMultiples(filepath.Join(fotosDir, "elenco3.jpg"))
 
 	if err != nil {
 		fmt.Println(err)
@@ -340,6 +344,36 @@ face-descriptor (ResNet) and CNN detector model files respectively —
 useful if you're using differently-named or fine-tuned dlib models. All
 three must be set before calling `Init`; they're read once, at load time.
 
+## Errors
+
+The "expected" failure conditions -- no face detected, more than one
+face detected, no dataset match, a missing dataset file -- are exposed
+as sentinel errors, so callers can branch on them with `errors.Is`
+instead of matching on the error message text (which isn't part of the
+API contract and may change):
+
+```go
+faces, err := rec.Identify(path)
+switch {
+case errors.Is(err, recognizer.ErrNotSingleFace):
+	// the image doesn't have exactly one face
+case errors.Is(err, recognizer.ErrNoMatch):
+	// no Dataset entry within Tolerance
+case err != nil:
+	// something else went wrong (I/O, decode, ...)
+}
+```
+
+| Error | Returned by |
+|-------|-------------|
+| `ErrNoFace` | `AddImageToDataset`, when the image has no detected face |
+| `ErrNotSingleFace` | `AddImageToDataset`, `RecognizeSingle`, `Identify`, when the image has more than one detected face (or, for `RecognizeSingle`/`Identify`, doesn't have exactly one) |
+| `ErrNoMatch` | `Identify`, when the face doesn't match any `Dataset` entry within `Tolerance` |
+| `ErrDatasetFileNotFound` | `LoadDataset`, when `Path` doesn't exist |
+
+Any other error (I/O, image decoding, etc.) is wrapped with `%w`, so
+`errors.Unwrap`/`errors.As` still reach the underlying cause.
+
 ## Contributing
 
 Issues and pull requests are welcome. If you're reporting a build problem,

dataset.go

@@ -2,7 +2,6 @@ package recognizer
 
 import (
 	"encoding/json"
-	"errors"
 	"os"
 )
 
@@ -32,14 +31,17 @@ func (_this *Recognizer) SaveDataset(Path string) error {
 /*
 LoadDataset loads the data from the json file into the Dataset.
 
-Call SetSamples afterward: as with AddImageToDataset, Classify and
-ClassifyMultiples won't see the loaded entries until SetSamples runs
+Returns ErrDatasetFileNotFound if Path doesn't exist -- check with
+errors.Is.
+
+Call SetSamples afterward: as with AddImageToDataset, Identify and
+IdentifyMultiples won't see the loaded entries until SetSamples runs
 again.
 */
 func (_this *Recognizer) LoadDataset(Path string) error {
 
 	if !fileExists(Path) {
-		return errors.New("file not found")
+		return ErrDatasetFileNotFound
 	}
 
 	file, err := os.Open(Path)

examples/recognition/main.go

@@ -12,6 +12,9 @@ const dataDir = "models"
 
 func addFile(rec *recognizer.Recognizer, Path, Id string) {
 
+	// AddImageToDataset returns recognizer.ErrNoFace/ErrNotSingleFace for
+	// images that don't have exactly one face -- check with errors.Is if
+	// you need to tell those apart; here we just log whatever comes back.
 	err := rec.AddImageToDataset(Path, Id)
 
 	if err != nil {
@@ -47,7 +50,7 @@ func main() {
 	// No rec.SetSamples() call needed here: AddImageToDataset already
 	// keeps the classifier in sync incrementally as each face is added.
 
-	faces, err := rec.ClassifyMultiples(filepath.Join(fotosDir, "elenco3.jpg"))
+	faces, err := rec.IdentifyMultiples(filepath.Join(fotosDir, "elenco3.jpg"))
 
 	if err != nil {
 		fmt.Println(err)

go.mod

@@ -8,4 +8,4 @@ require (
 	golang.org/x/image v0.44.0
 )
 
-require github.com/leandroveronezi/go-face v1.0.7
+require github.com/leandroveronezi/go-face v1.1.0

recognizer.go

@@ -12,6 +12,24 @@ import (
 	goFace "github.com/leandroveronezi/go-face"
 )
 
+// Sentinel errors for the "expected" failure conditions -- check for
+// these with errors.Is instead of matching on the error message text,
+// which isn't part of the API contract and may change.
+var (
+	// ErrNoFace is returned when an image has no detected face, where an
+	// operation requires at least one.
+	ErrNoFace = errors.New("not a face on the image")
+	// ErrNotSingleFace is returned when an image doesn't have exactly
+	// one detected face, where an operation requires exactly one.
+	ErrNotSingleFace = errors.New("not a single face on the image")
+	// ErrNoMatch is returned by Identify when the descriptor doesn't
+	// match any Dataset entry within Tolerance.
+	ErrNoMatch = errors.New("can't identify")
+	// ErrDatasetFileNotFound is returned by LoadDataset when Path
+	// doesn't exist.
+	ErrDatasetFileNotFound = errors.New("file not found")
+)
+
 // Data descriptor of the human face.
 type Data struct {
 	Id         string
@@ -27,11 +45,11 @@ type Face struct {
 	Shapes []image.Point
 	// Distance is the squared Euclidean distance between this face's
 	// descriptor and the matched Dataset entry's descriptor. Only set by
-	// Classify/ClassifyMultiples; zero otherwise.
+	// Identify/IdentifyMultiples; zero otherwise.
 	Distance float64
 	// Confidence is a convenience score in [0,1], normalized as
 	// 1-Distance/Tolerance -- not a calibrated probability. Only set by
-	// Classify/ClassifyMultiples; zero otherwise.
+	// Identify/IdentifyMultiples; zero otherwise.
 	Confidence float64
 }
 
@@ -143,6 +161,9 @@ func (_this *Recognizer) detect(Path string) ([]goFace.Face, error) {
 /*
 AddImageToDataset add a sample image to the dataset.
 
+Returns ErrNoFace if the image has no detected face, or ErrNotSingleFace
+if it has more than one -- check with errors.Is.
+
 The new entry is appended to the underlying classifier immediately (via
 goFace.AppendSample), so it's classifiable right away -- no need to call
 SetSamples afterward. SetSamples is still required after LoadDataset or
@@ -158,11 +179,11 @@ func (_this *Recognizer) AddImageToDataset(Path string, Id string) error {
 	}
 
 	if len(faces) == 0 {
-		return errors.New("Not a face on the image")
+		return ErrNoFace
 	}
 
 	if len(faces) > 1 {
-		return errors.New("Not a single face on the image")
+		return ErrNotSingleFace
 	}
 
 	f := Data{}
@@ -207,7 +228,8 @@ func (_this *Recognizer) SetSamples() {
 }
 
 /*
-RecognizeSingle returns face if it's the only face on the image or nil otherwise.
+RecognizeSingle returns the face on the image, or ErrNotSingleFace if it
+doesn't have exactly one -- check with errors.Is.
 */
 func (_this *Recognizer) RecognizeSingle(Path string) (goFace.Face, error) {
 
@@ -218,7 +240,7 @@ func (_this *Recognizer) RecognizeSingle(Path string) (goFace.Face, error) {
 
 		pixels, width, height, lerr := _this.loadPixels(Path)
 		if lerr != nil {
-			return goFace.Face{}, lerr
+			return goFace.Face{}, fmt.Errorf("can't recognize: %w", lerr)
 		}
 
 		if _this.UseCNN {
@@ -238,11 +260,11 @@ func (_this *Recognizer) RecognizeSingle(Path string) (goFace.Face, error) {
 	}
 
 	if err != nil {
-		return goFace.Face{}, fmt.Errorf("Can't recognize: %v", err)
+		return goFace.Face{}, fmt.Errorf("can't recognize: %w", err)
 
 	}
 	if idFace == nil {
-		return goFace.Face{}, fmt.Errorf("Not a single face on the image")
+		return goFace.Face{}, ErrNotSingleFace
 	}
 
 	return *idFace, nil
@@ -259,37 +281,41 @@ func (_this *Recognizer) RecognizeMultiples(Path string) ([]goFace.Face, error)
 	idFaces, err := _this.detect(Path)
 
 	if err != nil {
-		return nil, fmt.Errorf("Can't recognize: %v", err)
+		return nil, fmt.Errorf("can't recognize: %w", err)
 	}
 
 	return idFaces, nil
 
 }
 
 /*
-Classify returns all faces identified in the image. Empty list is returned if no match.
+Identify returns the single face identified in the image.
+
+Returns ErrNotSingleFace if the image doesn't have exactly one face, or
+ErrNoMatch if the face doesn't match any Dataset entry within Tolerance
+-- check with errors.Is.
 
 Matches against the sample set from the most recent SetSamples call, not
 necessarily the current Dataset -- see SetSamples.
 */
-func (_this *Recognizer) Classify(Path string) ([]Face, error) {
+func (_this *Recognizer) Identify(Path string) ([]Face, error) {
 
 	face, err := _this.RecognizeSingle(Path)
 
 	if err != nil {
 		return nil, err
 	}
 
-	personID := _this.rec.ClassifyThreshold(face.Descriptor, _this.Tolerance)
+	personID := _this.rec.IdentifyThreshold(face.Descriptor, _this.Tolerance)
 	if personID < 0 {
-		return nil, fmt.Errorf("Can't classify")
+		return nil, ErrNoMatch
 	}
 
 	_this.mu.RLock()
 	defer _this.mu.RUnlock()
 
 	if personID >= len(_this.Dataset) {
-		return nil, fmt.Errorf("Can't classify")
+		return nil, ErrNoMatch
 	}
 
 	matched := _this.Dataset[personID]
@@ -310,24 +336,26 @@ func (_this *Recognizer) Classify(Path string) ([]Face, error) {
 }
 
 /*
-ClassifyMultiples returns all faces identified in the image. Empty list is returned if no match.
+IdentifyMultiples returns every face identified in the image. Faces with
+no Dataset entry within Tolerance are skipped -- an empty slice (not an
+error) is returned if none matched.
 
 Matches against the sample set from the most recent SetSamples call, not
 necessarily the current Dataset -- see SetSamples.
 */
-func (_this *Recognizer) ClassifyMultiples(Path string) ([]Face, error) {
+func (_this *Recognizer) IdentifyMultiples(Path string) ([]Face, error) {
 
 	faces, err := _this.RecognizeMultiples(Path)
 
 	if err != nil {
-		return nil, fmt.Errorf("Can't recognize: %v", err)
+		return nil, err
 	}
 
 	facesRec := make([]Face, 0)
 
 	for _, f := range faces {
 
-		personID := _this.rec.ClassifyThreshold(f.Descriptor, _this.Tolerance)
+		personID := _this.rec.IdentifyThreshold(f.Descriptor, _this.Tolerance)
 		if personID < 0 {
 			continue
 		}