================================================================================
MIGRATION GUIDE (QUICK REFERENCE): Luxand FaceSDK .NET Wrapper
From Old Version (v8.2 and earlier) to New Version (v8.3+)
================================================================================

This is a condensed version of the migration guide.

================================================================================
QUICK OVERVIEW
================================================================================

Key Changes:
  • Classes are no longer nested (FSDK.Cam → Camera, FSDK.CImage → CImage)
  • Better parameter semantics (ref → in/out or removed)
  • New high-level classes: Tracker, Camera, CImage (standalone)
  • Improved error handling with CheckForError()
  • Better XML documentation and modern C# patterns
  • New features: Tracker enhancements, GetVersionInfo(), better IDisposable

================================================================================
CLASS MAPPING
================================================================================

OLD                          NEW
------------------------     ------------------------
FSDKCam (static)         →   Camera (static methods) / FSDK
FSDK.Cam                 →   Camera
FSDK.CImage              →   CImage
(no equivalent)          →   Tracker (NEW, recommended)
(no equivalent)          →   Helpers (NEW, for internal use)

================================================================================
KEY SIGNATURE CHANGES
================================================================================

1. Parameter Modifiers:
   OLD: ref (used for everything)
   NEW: in (input), out (output), or no modifier (simple input)

   Examples:
   • ref TFacePosition           → in TFacePosition
   • ref float similarity         → out float similarity
   • ref string cameraName        → string cameraName (no modifier)
   • ref byte[] template          → byte[] template (no modifier)

2. Common Method Changes:
   • DetectFace(img, ref pos)               → DetectFace(img, out pos)
   • DetectEyesInRegion(img, ref pos, ...)  → DetectEyesInRegion(img, in pos, ...)
   • MatchFaces(ref t1, ref t2, ref sim)    → MatchFaces(t1, t2, out sim)
   • GetMatchingThresholdAtFAR(f, ref t)    → GetMatchingThresholdAtFAR(f, out t)
   • CreateTracker(ref handle)              → CreateTracker(out handle)
   • FeedFrame(t, c, i, ref cnt, out ids)   → FeedFrame(t, c, i, out cnt, out ids)

================================================================================
CAMERA CHANGES
================================================================================

OLD:
  FSDKCam.InitializeCapturing();
  string[] cameras;
  int count;
  FSDKCam.GetCameraList(out cameras, out count);
  string camName = cameras[0];
  FSDK.Cam camera = new FSDK.Cam(ref camName);
  FSDK.CImage frame = camera.GrabFrame();

NEW:
  Camera.InitializeCapturing();
  string[] cameras = Camera.GetCameraList();
  Camera camera = new Camera(cameras[0]);
  CImage frame = camera.GrabFrame();

NEW (Better with using):
  using (Camera camera = new Camera(Camera.GetCameraList()[0])) {
      using (CImage frame = camera.GrabFrame()) {
          // Process frame
      }
  }

================================================================================
IMAGE HANDLING CHANGES
================================================================================

OLD:
  int handle = 0;
  FSDK.LoadImageFromFile(ref handle, "image.jpg");
  FSDK.CImage img = new FSDK.CImage(handle);
  FSDK.TFacePosition pos = new FSDK.TFacePosition();
  FSDK.DetectFace(img.ImageHandle, ref pos);

NEW:
  CImage img = new CImage("image.jpg");
  FSDK.TFacePosition pos = img.DetectFace();

================================================================================
DETECTION CHANGES
================================================================================

OLD:
  FSDK.TFacePosition[] faces;
  int detected = 0;
  FSDK.DetectMultipleFaces(imgHandle, ref detected, out faces, 256*24);
  
  FSDK.TPoint[] features;
  FSDK.DetectFacialFeaturesInRegion(imgHandle, ref facePos, out features);

NEW:
  FSDK.TFacePosition[] faces = img.DetectMultipleFaces();
  
  FSDK.TPoint[] features = img.DetectFacialFeaturesInRegion(facePos);

================================================================================
TEMPLATE MATCHING CHANGES
================================================================================

OLD:
  byte[] t1, t2;
  FSDK.GetFaceTemplate(img1, out t1);
  FSDK.GetFaceTemplateInRegion(img2, ref pos, out t2);
  float similarity = 0;
  FSDK.MatchFaces(ref t1, ref t2, ref similarity);

NEW:
  byte[] t1 = image1.GetFaceTemplate();
  byte[] t2 = image2.GetFaceTemplateInRegion(pos);
  FSDK.MatchFaces(t1, t2, out float similarity);

================================================================================
TRACKER CHANGES
================================================================================

OLD:
  int tracker = 0;
  FSDK.CreateTracker(ref tracker);
  FSDK.SetTrackerParameter(tracker, "RecognizeFaces", "true");
  
  long count = 0;
  long[] ids;
  FSDK.FeedFrame(tracker, 0, imgHandle, ref count, out ids, 1024);
  
  FSDK.TFacePosition pos = new FSDK.TFacePosition();
  FSDK.GetTrackerFacePosition(tracker, 0, ids[0], ref pos);
  
  FSDK.FreeTracker(tracker);

NEW (Option 1 - Direct FSDK):
  int tracker;
  FSDK.CreateTracker(out tracker);
  FSDK.SetTrackerParameter(tracker, "RecognizeFaces", "true");
  
  long count;
  long[] ids;
  FSDK.FeedFrame(tracker, 0, imgHandle, out count, out ids, 1024);
  
  FSDK.TFacePosition pos;
  FSDK.GetTrackerFacePosition(tracker, 0, ids[0], out pos);
  
  FSDK.FreeTracker(tracker);

NEW (Option 2 - Tracker class, RECOMMENDED):
  using (Tracker tracker = new Tracker()) {
      tracker.SetParameter("RecognizeFaces", "true");
      
      long[] ids;
      tracker.FeedFrame(image, out ids);
      
      foreach (long id in ids) {
          FSDK.TFacePosition pos = tracker.GetFacePosition(0, id);
          string name = tracker.GetName(id);
      }
  }

================================================================================
NEW TRACKER FEATURES (v8.3+)
================================================================================

New methods available only in new wrapper:
  • tracker.GetIDsCount() / GetAllIDs()
  • tracker.GetFaceIDsForID(id) / GetIDByFaceID(faceId)
  • tracker.GetFaceTemplate(faceId)
  • tracker.CreateID(template, out id, out faceId)
  • tracker.AddFaceTemplate(id, template, out faceId)
  • tracker.DeleteFace(faceId)
  • tracker.GetFaceImage(faceId) / SetFaceImage(faceId, img)
  • tracker.MatchFaces(template, threshold, out results)

================================================================================
ERROR HANDLING
================================================================================

OLD:
  int res = FSDK.LoadImageFromFile(ref handle, file);
  if (res != FSDK.FSDKE_OK)
      throw new Exception("Error: " + res);

NEW (Manual):
  int res = FSDK.LoadImageFromFile(out handle, file);
  if (res != FSDK.FSDKE_OK)
      throw new Exception("Luxand FaceSDK Error Number " + res);

NEW (Recommended):
  int res = FSDK.LoadImageFromFile(out handle, file);
  FSDK.CheckForError(res);

NEW (High-level classes):
  CImage img = new CImage(file); // Throws on error automatically

================================================================================
COMPLETE MIGRATION EXAMPLE
================================================================================

OLD CODE:
---------
FSDK.ActivateLibrary("key");
FSDK.InitializeLibrary();
FSDKCam.InitializeCapturing();

string[] cameras;
int count;
FSDKCam.GetCameraList(out cameras, out count);
string camName = cameras[0];
FSDK.Cam camera = new FSDK.Cam(ref camName);

int tracker = 0;
FSDK.CreateTracker(ref tracker);

while (running) {
    FSDK.CImage img = camera.GrabFrame();
    
    long faceCount = 0;
    long[] ids;
    FSDK.FeedFrame(tracker, 0, img.ImageHandle, ref faceCount, out ids, 1024);
    
    for (int i = 0; i < faceCount; i++) {
        FSDK.TPoint[] features;
        FSDK.GetTrackerFacialFeatures(tracker, 0, ids[i], out features);
        
        string name;
        FSDK.GetName(tracker, ids[i], out name, 1024);
        Console.WriteLine("Face: " + name);
    }
    
    img.Dispose();
}

camera.Dispose();
FSDK.FreeTracker(tracker);
FSDKCam.FinalizeCapturing();
FSDK.FinalizeLibrary();


NEW CODE (Recommended):
-----------------------
FSDK.ActivateLibrary("key");
FSDK.InitializeLibrary();
Camera.InitializeCapturing();

string[] cameras = Camera.GetCameraList();

using (Camera camera = new Camera(cameras[0]))
using (Tracker tracker = new Tracker()) {
    while (running) {
        using (CImage img = camera.GrabFrame()) {
            long[] ids;
            tracker.FeedFrame(img, out ids);
            
            if (ids != null) {
                foreach (long id in ids) {
                    FSDK.TPoint[] features = tracker.GetFacialFeatures(0, id);
                    string name = tracker.GetName(id);
                    Console.WriteLine("Face: " + name);
                }
            }
        }
    }
}

Camera.FinalizeCapturing();
FSDK.FinalizeLibrary();

================================================================================
MIGRATION CHECKLIST
================================================================================

Essential Steps:
  ☐ Replace all FSDKCam references with Camera
  ☐ Replace all FSDK.Cam references with Camera
  ☐ Replace all FSDK.CImage references with CImage
  ☐ Remove 'ref' from camera name parameters
  ☐ Change 'ref' to 'in' for TFacePosition input parameters
  ☐ Change 'ref' to 'out' for similarity, threshold, count outputs
  ☐ Remove 'ref' from template arrays (use plain arrays)
  ☐ Update tracker creation: CreateTracker(ref h) → CreateTracker(out h)
  ☐ Update FeedFrame: FeedFrame(..., ref count, ...) → FeedFrame(..., out count, ...)
  ☐ Update GetTrackerFacePosition: (..., ref pos) → (..., out pos)
  ☐ Consider using high-level Tracker class instead of manual handle
  ☐ Use CheckForError() for error handling
  ☐ Test all camera, detection, and tracker operations

Recommended Improvements:
  ☐ Use 'using' statements for Camera, CImage, Tracker
  ☐ Use CImage methods (DetectFace, GetFaceTemplate) instead of FSDK static methods
  ☐ Use Tracker class methods instead of direct FSDK tracker calls
  ☐ Explore new v8.3 features (GetAllIDs, MatchFaces, etc.)

================================================================================
COMMON PATTERNS
================================================================================

Pattern 1: Camera + Face Detection
-----------------------------------
OLD: FSDK.Cam cam = new FSDK.Cam(ref name); ... DetectFace(h, ref pos);
NEW: using (Camera cam = new Camera(name)) { pos = img.DetectFace(); }

Pattern 2: Template Matching
-----------------------------
OLD: MatchFaces(ref t1, ref t2, ref sim);
NEW: MatchFaces(t1, t2, out sim);

Pattern 3: Tracker Operations
------------------------------
OLD: CreateTracker(ref h); SetTrackerParameter(h, ...); FreeTracker(h);
NEW: using (Tracker t = new Tracker()) { t.SetParameter(...); }

Pattern 4: Multiple Face Detection
-----------------------------------
OLD: DetectMultipleFaces(h, ref count, out faces, size);
NEW: faces = img.DetectMultipleFaces();

================================================================================
PERFORMANCE & COMPATIBILITY
================================================================================

Performance:
  • No performance difference - same native library used
  • High-level classes add minimal overhead
  • Memory management is more robust in new wrapper

Compatibility:
  • Same native FaceSDK library required
  • No changes to license activation process
  • No changes to data files or configuration

Thread Safety:
  • Same as before - most operations thread-safe
  • Tracker and Camera need synchronization for multi-threaded access

================================================================================
NEW FEATURES SUMMARY
================================================================================

1. Tracker class: High-level OOP interface for tracker operations
2. GetVersionInfo(): Get FaceSDK version information
3. Enhanced tracker database operations (GetAllIDs, MatchFaces, etc.)
4. Better IDisposable implementation with explicit Close() methods
5. Helpers class for string encoding (internal use)
6. Comprehensive XML documentation on all public APIs
7. New error codes (PLUGIN_NOT_LOADED, FACEID_NOT_FOUND, etc.)
8. Additional CImage methods (GetImageBufferSize, LoadImageFromBuffer, etc.)

================================================================================
SUPPORT & RESOURCES
================================================================================

Full FaceSDK API Documentation: https://www.luxand.com/facesdk/documentation/
Luxand Support: Contact for migration assistance
Source Code: Check wrapper source for detailed XML comments

================================================================================
QUICK REFERENCE TABLE
================================================================================

Old Syntax                                   New Syntax
------------------------------------------   ------------------------------------------
FSDKCam.InitializeCapturing()                Camera.InitializeCapturing()
FSDKCam.GetCameraList(out c, out n)          c = Camera.GetCameraList()
new FSDK.Cam(ref name)                       new Camera(name)
new FSDK.CImage(file)                        new CImage(file)
DetectFace(h, ref pos)                       DetectFace(h, out pos)
DetectEyesInRegion(h, ref p, out f)          DetectEyesInRegion(h, in p, out f)
GetFaceTemplate(h, out t)                    img.GetFaceTemplate()
GetFaceTemplateInRegion(h, ref p, out t)     GetFaceTemplateInRegion(h, in p, out t)
MatchFaces(ref t1, ref t2, ref s)            MatchFaces(t1, t2, out s)
GetMatchingThresholdAtFAR(f, ref t)          GetMatchingThresholdAtFAR(f, out t)
CreateTracker(ref h)                         CreateTracker(out h) or new Tracker()
FeedFrame(t, c, i, ref n, out ids, s)        FeedFrame(t, c, i, out n, out ids, s)
GetTrackerFacePosition(t, c, i, ref p)       GetTrackerFacePosition(t, c, i, out p)

================================================================================
END OF QUICK REFERENCE GUIDE
================================================================================

For detailed information, examples, and explanations, please refer to the
complete migration guide in readme.txt.

Last Updated: December 2025
For FaceSDK version: 8.3+
