이미지에서 가속화된 도형 감지

1. 소개

사진과 이미지는 웹에서 가장 큰 비중을 차지하며, 많은 이미지에는 사람 얼굴이나 바코드/QR 코드와 같은 인식 가능한 특징이 포함되어 있습니다. 이러한 특징을 감지하는 것은 계산 비용이 많이 들지만 얼굴 태깅이나 웹 URL 리디렉션과 같은 흥미로운 사용 사례로 이어질 수 있습니다. 하드웨어 제조업체는 오랜 기간 이러한 기능을 지원해 왔지만 웹 앱은 아직 이러한 하드웨어 기능에 접근할 수 없어 연산 비용이 큰 라이브러리 사용이 필요합니다.

텍스트 감지는 흥미로운 분야임에도 불구하고 이 문서의 맥락에서 컴퓨팅 플랫폼이나 문자 집합 전반에서 충분히 안정적이라고 보기 어렵기 때문에 표준화 대상에 포함되지 않습니다. 참고용으로 자매 정보 명세는 [TEXT-DETECTION-API]에 보관되어 있습니다.

1.1. 도형 감지 활용 사례

저장소의 Readme/Explainer를 참조하세요.

2. 도형 감지 API

개별 브라우저는 가속화된 동작을 제공하는 하드웨어의 사용 가능성을 나타내는 Detectors를 제공할 수 있습니다.

이미지에서 특징을 감지하는 작업은 비동기적으로 수행되며, 브라우저와 독립적으로 가속 하드웨어와 통신할 수 있습니다. 완료 이벤트는 shape detection task source를 사용합니다.

2.1. 감지를 위한 이미지 소스

이 섹션은 HTML Canvas 2D Context § image-sources-for-2d-rendering-contexts에서 영감을 받았습니다.

ImageBitmapSource 는 여러 인터페이스를 구현하는 객체들이 감지 프로세스의 이미지 소스로 사용될 수 있도록 허용합니다.

• 만약 ImageBitmapSource 객체가 HTMLImageElement를 나타내면, 해당 요소의 이미지를 소스 이미지로 사용해야 합니다. 특히 ImageBitmapSource 객체가 HTMLImageElement의 애니메이션화된 이미지를 나타내는 경우, 사용자 에이전트는 애니메이션의 기본 이미지(포맷이 애니메이션을 지원하지 않거나 비활성화된 경우 사용하도록 정의된 이미지)를 사용해야 하며, 그런 이미지가 없다면 애니메이션의 첫 번째 프레임을 사용해야 합니다.

• 만약 ImageBitmapSource 객체가 HTMLVideoElement를 나타내면, 해당 메서드가 호출될 때의 현재 재생 위치의 프레임을 소스 이미지로 사용해야 하며, 소스 이미지의 크기는 미디어 리소스의 intrinsic dimensions(즉 종횡비 보정이 적용된 후의 크기)여야 합니다.

• 만약 ImageBitmapSource 객체가 HTMLCanvasElement를 나타내면, 해당 요소의 비트맵을 소스 이미지로 사용해야 합니다.

UA가 특정 디텍터의 detect() 메서드에 대해 주어진 유형의 ImageBitmapSource 을 입력 인수로 사용해야 할 때, 다음 단계를 실행해야 합니다:

• 만약 어떤 ImageBitmapSource 의 유효한 스크립트 출처(origin)가 문서의 유효한 스크립트 출처와 동일하지 않으면, 이름이 SecurityError인 새로운 DOMException으로 Promise를 거부해야 합니다.

• 만약 ImageBitmapSource 가 HTMLImageElement이고 그 요소가 Broken 상태(HTML Standard §img-error)이면, 이름이 InvalidStateError인 새로운 DOMException으로 Promise를 거부하고 이후 단계를 중단해야 합니다.

• 만약 ImageBitmapSource 가 완전히 디코딩될 수 없는 HTMLImageElement 객체이면, 이름이 InvalidStateError인 새로운 DOMException으로 Promise를 거부하고 이후 단계를 중단해야 합니다.

• 만약 ImageBitmapSource 가 HTMLVideoElement 객체이고 그 readyState 속성이 HAVE_NOTHING 또는 HAVE_METADATA 라면, 이름이 InvalidStateError인 새로운 DOMException으로 Promise를 거부하고 이후 단계를 중단해야 합니다.

• 만약 ImageBitmapSource 인수가 HTMLCanvasElement이고 해당 캔버스 비트맵의 origin-clean (HTML Standard §concept-canvas-origin-clean) 플래그가 false이면, 이름이 SecurityError인 새로운 DOMException으로 Promise를 거부하고 이후 단계를 중단해야 합니다.

참고로, ImageBitmapSource 가 가로 또는 세로 치수 중 하나가 0인 객체인 경우, Promise는 단순히 빈 검출 결과 시퀀스로 이행됩니다.

2.2. 얼굴 감지 API

FaceDetector 는 이미지에서 사람 얼굴을 감지하기 위한 기저 가속 플랫폼 구성요소를 나타냅니다. 선택적 사전(Dictionary) FaceDetectorOptions로 생성할 수 있습니다. 이 객체는 detect() 단일 연산을 제공하며, 입력으로 ImageBitmapSource 를 받아 Promise를 반환합니다. 이 메서드는 § 2.1 Image sources for detection에 상세히 명시된 경우들에서는 반드시 이 Promise를 거부해야 하며; 그렇지 않은 경우 운영체제/플랫폼 자원을 활용하는 작업을 큐잉하여 각 검출된 객체가 본질적으로 boundingBox로 구분되는 DetectedFace의 시퀀스로 Promise를 이행할 수 있습니다.

[Exposed=(Window,Worker),
 SecureContext]
interface FaceDetector {
  constructor(optional FaceDetectorOptions faceDetectorOptions = {});
  Promise<sequence<DetectedFace>> detect(ImageBitmapSource image);
};

FaceDetector(optional FaceDetectorOptions faceDetectorOptions)

선택적 faceDetectorOptions로 새로운 FaceDetector를 구성합니다.

Detectors는 상당한 자원을 할당하고 보유할 수 있습니다. 가능한 경우 여러 검출에 동일한 FaceDetector를 재사용하세요.

detect(ImageBitmapSource image)

주어진 ImageBitmapSource image에서 사람 얼굴을 감지하려 시도합니다. 검출된 얼굴(있는 경우)은 DetectedFace의 시퀀스로 반환됩니다.

2.2.1. FaceDetectorOptions

dictionary FaceDetectorOptions {
  unsigned short maxDetectedFaces;
  boolean fastMode;
};

maxDetectedFaces, 타입은 unsigned short

UA에게 장면에서 감지되는 얼굴 수를 이 최대값으로 제한하도록 시도하라는 힌트입니다.

fastMode, 타입은 boolean

UA에게 예를 들어 축소된 스케일로 연산하거나 큰 특징만 찾는 등 정확도보다 속도를 우선하도록 시도하라는 힌트입니다.

2.2.2. DetectedFace

dictionary DetectedFace {
  required DOMRectReadOnly boundingBox;
  required sequence<Landmark>? landmarks;
};

boundingBox, 타입은 DOMRectReadOnly

검출된 특징의 위치와 범위를 이미지 축에 정렬된 직사각형으로 나타냅니다.

landmarks, 타입은 sequence<Landmark> nullable

검출된 특징과 관련된 관심 특징들의 일련입니다.

dictionary Landmark {
  required sequence<Point2D> locations;
  LandmarkType type;
};

locations, 타입은 sequence<Point2D>

검출된 랜드마크의 중심에 있는 점이거나, 시계방향 또는 반시계방향으로 랜드마크를 둘러싼 단순 다각형의 정점을 정의하는 점들의 시퀀스일 수 있습니다.

type, 타입은 LandmarkType

알려진 경우 랜드마크의 유형입니다.

enum LandmarkType {
  "mouth",
  "eye",
  "nose"
};

mouth

랜드마크가 사람의 입으로 식별됩니다.

eye

랜드마크가 사람의 눈으로 식별됩니다.

nose

랜드마크가 사람의 코로 식별됩니다.

[SameObject] readonly attribute unsigned long id;

2.3. 바코드 감지 API

BarcodeDetector 는 이미지에서 선형 또는 2차원 바코드를 감지하기 위한 기저 가속 플랫폼 구성요소를 나타냅니다. 이 객체는 detect() 단일 연산을 제공하며, 입력으로 ImageBitmapSource 를 받아 Promise를 반환합니다. 이 메서드는 § 2.1 Image sources for detection에 상세히 명시된 경우들에서는 반드시 이 Promise를 거부해야 하며; 그렇지 않은 경우 운영체제/플랫폼 자원을 사용하는 작업을 큐잉하여 각 검출된 객체가 본질적으로 boundingBox 와 일련의 Point2D들로 구성되고, 경우에 따라 디코딩된 rawValue (타입 DOMString)를 포함하는 DetectedBarcode의 시퀀스로 Promise를 이행할 수 있습니다.

[Exposed=(Window,Worker),
 SecureContext]
interface BarcodeDetector {
  constructor(optional BarcodeDetectorOptions barcodeDetectorOptions = {});
  static Promise<sequence<BarcodeFormat>> getSupportedFormats();

  Promise<sequence<DetectedBarcode>> detect(ImageBitmapSource image);
};

BarcodeDetector(optional BarcodeDetectorOptions barcodeDetectorOptions)

barcodeDetectorOptions로 새로운 BarcodeDetector를 구성합니다.

• 만약 barcodeDetectorOptions.formats 가 존재하고 비어 있으면, 새로운 TypeError를 던집니다.

• 만약 barcodeDetectorOptions.formats 가 존재하고 unknown을 포함하면, 새로운 TypeError를 던집니다.

Detectors는 상당한 자원을 할당하고 보유할 수 있습니다. 가능한 경우 여러 검출에 동일한 BarcodeDetector를 재사용하세요.

getSupportedFormats()

이 메서드는 호출될 때 새로운 Promise promise를 반환하고 다음 단계들을 병렬로 실행해야 합니다:

1. supportedFormats를 새로운 Array로 둡니다.
2. 만약 UA가 바코드 감지를 지원하지 않으면, 글로벌 태스크를 이 관련 전역 객체에서 resolve하여 promise를 supportedFormats와 함께 이행하고 단계를 종료합니다.
3. UA가 이미지에서 잠재적으로 감지할 수 있는 BarcodeFormat들을 열거하여 supportedFormats에 추가합니다.
   UA는 심볼의 위치나 인코딩 오류 등으로 인해 특정 바코드 형식이 이미지에서 항상 인식될지에 대해 확정적인 답을 줄 수 없습니다. 그러나 특정 바코드 기호가 supportedFormats 배열에 없으면, 그 형식은 전혀 감지될 수 없어야 합니다.
4. 글로벌 태스크를 이 관련 전역 객체에서 shape detection task source를 사용하여 resolve하여 promise를 supportedFormats와 함께 이행합니다.

지원되는 BarcodeFormat 목록은 플랫폼에 따라 달라지며, 예로는 Google Play Services와 Apple의 QICRCodeFeature에서 지원되는 형식들이 있습니다.

detect(ImageBitmapSource image)

주어진 ImageBitmapSource image에서 바코드를 감지하려 시도합니다.

2.3.1. BarcodeDetectorOptions

dictionary BarcodeDetectorOptions {
  sequence<BarcodeFormat> formats;
};

formats, 유형 sequence<BarcodeFormat>

이후 detect() 호출에서 탐색할 BarcodeFormat의 리스트입니다. 지정하지 않으면 UA가 지원하는 모든 포맷을 탐색해야 합니다.

지원하는 포맷의 일부로만 검색을 제한하면 성능이 더 좋아질 수 있습니다.

2.3.2. DetectedBarcode

dictionary DetectedBarcode {
  required DOMRectReadOnly boundingBox;
  required DOMString rawValue;
  required BarcodeFormat format;
  required sequence<Point2D> cornerPoints;
};

boundingBox, 유형 DOMRectReadOnly

이미지 축에 맞게 정렬된 검출된 특징의 위치와 범위를 나타내는 직사각형

rawValue, 유형 DOMString

바코드에서 디코딩된 문자열입니다. 이 값은 여러 줄일 수 있습니다.

format, 유형 BarcodeFormat

감지된 BarcodeFormat.

cornerPoints, 유형 sequence<Point2D>

검출된 바코드의 꼭짓점을 시계 방향, 왼쪽 위부터 나열한 시퀀스입니다. 원근 왜곡으로 인해 꼭 정사각형이 아닐 수 있습니다.

2.3.3. BarcodeFormat

enum BarcodeFormat {
  "aztec",
  "code_128",
  "code_39",
  "code_93",
  "codabar",
  "data_matrix",
  "ean_13",
  "ean_8",
  "itf",
  "pdf417",
  "qr_code",
  "unknown",
  "upc_a",
  "upc_e"
};

aztec

이 항목은 [iso24778] 표준을 따르는 정사각형 2차원 매트릭스로, 중앙에 정사각형 bullseye 패턴이 있어 아즈텍 피라미드와 비슷합니다. 주변의 공백 영역이 필요하지 않습니다.

code_128

Code 128은 1차원 선형, 양방향 디코딩 가능, 자체 체크 바코드이며 [iso15417] 표준을 따릅니다. ASCII 전체 128문자를 인코딩할 수 있습니다.

code_39

이 항목은 Code 39 바코드에 관한 것으로, 불연속적이고 가변 길이의 바코드 유형입니다. [iso16388]

code_93

Code 93은 가변 길이의 연속형 1차원 심볼로 [bc5]를 따릅니다. 정보 밀도는 Code 128 및 시각적으로 유사한 Code 39보다 높으며, 캐나다 우체국 등에서 보조 배송 정보를 인코딩하는 데 주로 사용됩니다.

codabar

Codabar는 1972년 Pitney Bowes Corp.에서 개발된 선형 바코드 심볼로,

data_matrix

Data Matrix는 [iso16022]를 따르는, 정사각형 또는 직사각형 패턴으로 배열된 흑백 모듈로 구성된 방향 무관 2차원 바코드입니다.

ean_13

EAN-13은 UPC-A 기반의 선형 바코드로 [iso15420] 에 정의되어 있습니다. 유럽에서 원래 12자리 UPC 시스템(미국서 개발된)의 상위셋으로 만들어졌으며(UPC-A 코드는 EAN-13에서 첫 글자가 0으로 할당됩니다).

ean_8

EAN-8은 [iso15420] 에 정의된 선형 바코드이며 EAN-13에서 유래되었습니다.

itf

ITF14 바코드는 Interleaved 2 of 5를 기반으로 GS1에서 설계된 글로벌 트레이드 아이템 넘버 인코딩용 연속, 자체 체크, 양방향 디코딩이 가능한 코드로 항상 14자리를 인코딩합니다. 과거 배송 업계 등에 사용됐으나 Code 128로 대체됐습니다. [bc2]

pdf417

PDF417은 표준 [iso15438] 에 따른, 다수의 행과 열로 이루어진 연속형 2차원 바코드 심볼로 양방향 디코딩이 가능합니다.

qr_code

QR Code는 [iso18004] 표준을 준수하는 2차원 바코드로, 인코딩 정보는 텍스트, URL 또는 기타 데이터일 수 있습니다.

unknown

이 값은 해당 바코드 포맷을 감지하거나 지원하는지 플랫폼이 모름을 나타냅니다.

upc_a

UPC-A는 미국 소매에서 가장 널리 사용되는 표준 선형 바코드 중 하나로 [iso15420] 에 정의되어 있습니다. 각 숫자는 2개의 바와 2개의 공백 패턴으로 인코딩되며 총 12자리를 나타냅니다. 사실상 EAN-13의 부분집합이고, UPC-A 코드는 EAN-13에서 첫 자리를 0으로 하여 취급됩니다.

upc_e

UPC-E 바코드는 UPC-A 의 변형으로 [iso15420] 에 정의되어 있으며, 불필요한 0을 줄여 더 콤팩트하게 만든 바코드 입니다.

3. 보안 및 개인정보 고려사항

이 섹션은 비규범적입니다.

이 인터페이스는 이미지 소스의 콘텐츠에 관한 정보를 노출합니다. 구현 시 이미지 소스가 평소라면 보호되는 상황에서도 이 API로 검사될 수 있도록 우회가 일어나지 않게 반드시 보호 조치가 필요합니다. § 2.1 감지를 위한 이미지 소스에서 이를 위한 알고리즘을 설명합니다.

고성능 도형 감지 기능을 제공함으로써, 이 인터페이스는 개발자가 로컬 기기에서 이미지 분석 작업을 수행할 수 있게 해줍니다. 이는 연산을 원격 시스템으로 오프로드하는 것보다 개인정보 측면에서 이점이 있습니다. 개발자는 이 인터페이스에서 반환된 결과 역시 원본 이미지만큼이나 민감한 개인정보로 간주해야 합니다.

4. 예시

이 섹션은 비규범적입니다.

이 예제들의 약간 수정/확장 버전(및 기타 예시)은 이 codepen 모음에서 볼 수 있습니다.

4.1. 플랫폼의 감지기 지원 여부 확인

if (window.FaceDetector == undefined) {
  console.error('Face Detection not supported on this platform');
}
if (window.BarcodeDetector == undefined) {
  console.error('Barcode Detection not supported on this platform');
}

4.2. 얼굴 감지

let faceDetector = new FaceDetector({fastMode: true, maxDetectedFaces: 1});
// Assuming |theImage| is e.g. a <img> content, or a Blob.

faceDetector.detect(theImage)
.then(detectedFaces => {
  for (const face of detectedFaces) {
    console.log(
        ' Face @ (${face.boundingBox.x}, ${face.boundingBox.y}),' +
        ' size ${face.boundingBox.width}x${face.boundingBox.height}');
  }
}).catch(() => {
  console.error("Face Detection failed, boo.");
})

4.3. 바코드 감지

let barcodeDetector = new BarcodeDetector();
// Assuming |theImage| is e.g. a <img> content, or a Blob.

barcodeDetector.detect(theImage)
.then(detectedCodes => {
  for (const barcode of detectedCodes) {
    console.log(' Barcode ${barcode.rawValue}' +
        ' @ (${barcode.boundingBox.x}, ${barcode.boundingBox.y}) with size' +
        ' ${barcode.boundingBox.width}x${barcode.boundingBox.height}');
  }
}).catch(() => {
  console.error("Barcode Detection failed, boo.");
})