Windows SDK

v1.0.0

MetsaKuur.FaceSdk

Windows 키오스크 환경에서 얼굴 등록과 식별을 하나의 흐름으로 통합하는 .NET SDK입니다. 카메라 제어, 품질 프레임 대기, Fidox 연동을 일관된 API로 제공합니다.

.NET 8.0Windows 10 1809+x64 onlyC# / .NET

빠른 시작

전체 흐름

CreateClient

FaceSdk.CreateClient()로 클라이언트 생성

InitializeAsync

라이선스 검증, 엔진 초기화, Fidox 연동 설정

StartCameraAsync

카메라 장치 열기 및 스트리밍 시작

WaitForQualifiedFrameAsync

품질 충족 프레임이 연속으로 확보될 때까지 대기

RegisterAsync / IdentifyAsync

얼굴 등록 또는 1:N 식별 수행

StopCameraAsync

카메라 중지 및 장치 닫기

ShutdownAsync

전역 자원 정리

using MetsaKuur.FaceSdk;
using MetsaKuur.FaceSdk.Options;

await using var client = FaceSdk.CreateClient();

await client.InitializeAsync(new FaceClientOptions
{
    License = new LicenseValidationOptions
    {
        CustomerId = "sample-client",
        ProductCode = "MetsaKuur.FaceSdk.Sample"
    },
    Camera = new CameraOptions
    {
        BackendType = CameraBackendType.MediaCapture
    },
    Recognition = new FaceRecognitionOptions
    {
        MinQualifiedFaceWidth = 100f,
        RequiredConsecutiveFrames = 5
    },
    Fidox = new FidoxGatewayOptions
    {
        BaseUrl = "https://api.fidox.co",
        AccessKey = "your-access-key",
        SecretKey = "your-secret-key"
    }
});

await client.StartCameraAsync();
await client.WaitForQualifiedFrameAsync(
    timeout: TimeSpan.FromSeconds(10));

var reg = await client.RegisterAsync("user-001", name: "홍길동");
var id  = await client.IdentifyAsync(withLiveness: false);

await client.StopCameraAsync();
await FaceSdk.ShutdownAsync();

사용 흐름

1. 초기화

FaceSdk.CreateClient() 호출
InitializeAsync(options) 호출
라이선스 검증 수행
얼굴 엔진 초기화
카메라 서비스 초기화
Fidox 게이트웨이 초기화 + 디바이스 자동 등록

실패 가능 예외

LicenseValidationException
FaceEngineInitializationException
CameraInitializationException

2. 품질 충족 프레임 대기

카메라 프레임을 반복 수집하면서 아래 조건을 모두 충족하는 프레임이 연속으로 확보될 때까지 대기합니다.

얼굴이 1개 이상 검출
가장 큰 얼굴 폭 ≥ MinQualifiedFaceWidth
RequiredConsecutiveFrames 횟수 연속 충족

var result = await client.WaitForQualifiedFrameAsync(
    timeout: TimeSpan.FromSeconds(10),
    onPreviewFrame: frame =>
    {
        // 매 프레임마다 UI 갱신 등 활용
        // frame.Analysis.IsQualified: 현재 품질 충족 여부
    }
);

// result.CapturedImageBase64: 캡처 이미지
// result.Frame, result.Analysis 포함

디바이스 등록 정책

디바이스 등록은 기본적으로 자동 수행됩니다
DeviceCode 지정 시 해당 값 사용
DeviceName 미지정 시 SDK 기본값 사용
DeviceId 미지정 시 FidoxSDK가 fingerprint 생성
DeviceType은 항상 kiosk (내부 고정값)

// 고정 DeviceId로 포맷 후에도 같은 디바이스 유지
Fidox = new FidoxGatewayOptions
{
    BaseUrl = "https://api.fidox.co",
    AccessKey = "your-access-key",
    SecretKey = "your-secret-key",
    DeviceName = "1층 로비 키오스크",
    DeviceId   = "KIOSK-1F-LOBBY"
}

API 레퍼런스

IFaceClient 인터페이스의 공개 메서드 목록입니다.

메서드	반환값	설명
`InitializeAsync(options)`	Task	SDK 초기화 (라이선스, 엔진, 카메라, Fidox)
`StartCameraAsync()`	Task	카메라 시작
`StopCameraAsync()`	Task	카메라 중지
`WaitForQualifiedFrameAsync(...)`	Task<QualifiedFrameResult>	품질 충족 프레임 대기
`RegisterAsync(userId, name?)`	Task<RegisterResult>	얼굴 등록
`IdentifyAsync(withLiveness?)`	Task<IdentifyResult>	1:N 얼굴 식별

RegisterAsync

현재 카메라 캡처 이미지를 사용해 사용자를 등록합니다. WaitForQualifiedFrameAsync 이후에 호출해야 합니다.

매개변수

userId * — 사용자 식별자
name — 표시 이름 (선택)

반환값 (RegisterResult)

Success — 성공 여부
ErrorCode — 실패 코드
Message — 설명
TxId — 트랜잭션 ID

var result = await client.RegisterAsync(
    userId: "user-001",
    name: "홍길동"
);

if (result.Success)
    Console.WriteLine($"등록 완료: {result.TxId}");
else
    Console.WriteLine(
        $"실패: [{result.ErrorCode}] {result.Message}");

IdentifyAsync

현재 카메라 캡처 이미지를 사용해 등록된 전체 DB에서 일치하는 사용자를 찾습니다.

매개변수

withLiveness — 라이브니스 검사 여부 (기본: false)

반환값 (IdentifyResult)

Success — 성공 여부
Matched — 일치 여부
UserId / Name — 식별된 사용자
Score — 유사도
ErrorCode / Message

var result = await client.IdentifyAsync(
    withLiveness: false
);

if (result.Matched)
    Console.WriteLine(
        $"식별 성공: {result.UserId} ({result.Name})" +
        $" 유사도: {result.Score:F2}");
else
    Console.WriteLine(
        $"식별 실패: [{result.ErrorCode}] {result.Message}");

WaitForQualifiedFrameAsync

프레임마다 얼굴을 분석하여 품질 조건이 연속으로 충족될 때까지 대기합니다. 시간 초과 시 QualifiedFrameTimeoutException이 발생합니다.

매개변수

timeout — 최대 대기 시간
onPreviewFrame — 프레임별 콜백 (UI 갱신 등)
cancellationToken — 외부 취소

반환값 (QualifiedFrameResult)

Frame
Analysis
CapturedImageBase64

try
{
    await client.WaitForQualifiedFrameAsync(
        timeout: TimeSpan.FromSeconds(10),
        onPreviewFrame: frame =>
        {
            // frame.Analysis.FaceWidth 등 활용
        }
    );
}
catch (QualifiedFrameTimeoutException)
{
    // 사용자에게 재시도 안내
    Console.WriteLine("얼굴을 카메라에 가까이 대어주세요.");
}

옵션

FaceRecognitionOptions

옵션	설명
`MinQualifiedFaceWidth`	품질 충족 후보로 인정할 최소 얼굴 폭 (float)
`RequiredConsecutiveFrames`	품질 충족 상태가 유지되어야 하는 연속 프레임 수

Recognition = new FaceRecognitionOptions
{
    MinQualifiedFaceWidth = 100f,
    RequiredConsecutiveFrames = 5
}

FidoxGatewayOptions

옵션	설명
`BaseUrl`*	Fidox API 서버 URL
`AccessKey`*	API Access Key
`SecretKey`*	API Secret Key
`DeviceCode`	기존 발급 디바이스 코드 (선택)
`DeviceName`	디바이스 표시 이름 (선택)
`DeviceId`	고정 장비 식별값 (선택)

Fidox = new FidoxGatewayOptions
{
    BaseUrl   = "https://api.fidox.co",
    AccessKey = "your-access-key",
    SecretKey = "your-secret-key",
    // 선택값 — 필요할 때만 지정
    DeviceName = "1층 로비 키오스크",
    DeviceId   = "KIOSK-1F-LOBBY"
}

ℹ

인증 정보는 설정 파일로 분리하세요

AccessKey와 SecretKey를 코드에 하드코딩하지 말고 Config.ini 등 외부 파일에서 읽어오세요. 인증 정보가 변경되어도 설정 파일만 수정하면 됩니다.

[Fidox]
BaseUrl=https://api.fidox.co
AccessKey=ak_xxx
SecretKey=sk_xxx

CameraOptions

BackendType — 카메라 구현 선택

현재 지원되는 백엔드 타입은 CameraBackendType.MediaCapture입니다.

Camera = new CameraOptions
{
    BackendType = CameraBackendType.MediaCapture
}

예외 및 오류

초기화 및 카메라 관련 오류는 예외로, 등록/식별 실패는 결과 객체로 반환됩니다.

주요 예외

LicenseValidationException

라이선스 검증 실패 (초기화 중)

라이선스 정보, 실행 환경, x64 여부 확인

FaceSdkNotInitializedException

InitializeAsync 호출 전에 API 사용

InitializeAsync()가 정상 완료됐는지 확인

CameraException

카메라 열기/스트리밍 실패

장치 점유, 권한, 카메라 백엔드 설정 확인

QualifiedFrameTimeoutException

제한 시간 내 품질 프레임 미확보

얼굴 크기, 조명, MinQualifiedFaceWidth 확인

결과 객체 실패 코드

등록/식별 실패는 예외 대신 결과 객체로 반환됩니다.

AUTH_ERROR — 인증 실패
API_ERROR — API 오류
NETWORK_ERROR — 네트워크 오류
UNEXPECTED_ERROR — 예기치 않은 오류

try
{
    await client.InitializeAsync(options);
    await client.StartCameraAsync();
    await client.WaitForQualifiedFrameAsync(
        timeout: TimeSpan.FromSeconds(10));
}
catch (LicenseValidationException ex)
{
    Console.WriteLine($"라이선스 오류: {ex.Message}");
    return;
}
catch (QualifiedFrameTimeoutException)
{
    Console.WriteLine("얼굴을 다시 인식해주세요.");
    return;
}

var result = await client.IdentifyAsync();
if (!result.Success)
    Console.WriteLine(
        $"식별 실패: [{result.ErrorCode}] {result.Message}");

트러블슈팅

등록은 성공하지만 식별만 실패

withLiveness 설정 확인
Fidox AccessKey / SecretKey 확인
식별 응답 스키마와 SDK 파서 일치 여부
서버 로그와 클라이언트 결과 비교

최대 재시도 횟수 초과 메시지

실제 네트워크 연결 상태 확인
원본 응답 및 JSON 파싱 예외 여부 확인
SDK 버전 확인

사용자 미식별 또는 낮은 점수

등록 이미지 품질 확인
실시간 캡처 품질 확인
얼굴 각도 및 조명 상태
withLiveness 옵션 사용 여부

QualifiedFrameTimeoutException 반복 발생

얼굴이 충분히 크게 잡히는지 확인
조명 상태 개선
카메라 해상도 확인
MinQualifiedFaceWidth 값 조정
RequiredConsecutiveFrames 값 완화

권장 운영 로그 항목

초기화 성공 여부
카메라 시작/중지 여부
품질 프레임 대기 시간
등록/식별 결과 코드
식별 점수
예외 타입과 메시지

도움이 필요하신가요?

SDK 연동 중 문제가 발생하면 기술 지원팀에 문의해주세요.

기술 지원 문의