이미지 클라우드 인식 웹 개발자 가이드

웹에서 이미지 클라우드 인식을 구현하는 핵심 프로세스는 다음과 같은 주요 단계를 포함합니다: 먼저 브라우저를 통해 카메라를 호출하여 실시간 화면을 캡처하고, 수집된 이미지 데이터를 클라우드 서버에 업로드하여 인식 처리를 수행한 후, 클라우드에서 반환된 결과를 수신 및 분석하여 전체 이미지 인식 순환 구조를 완료합니다.

개발 단계

다른 브라우저는 카메라 처리 구현 방식에 차이가 있으며, 이 예제 코드는 모든 브라우저 호환성 문제를 다루지 않습니다. 실제 환경에 따라 조정하는 것이 좋습니다.

프로세스는 다음과 같습니다:

flowchart LR

A((카메라 초기화)) --> B[카메라 이미지 캡처] --> C{클라우드 인식 API 호출}
C ----> |대상 미인식| B
C ----> |대상 인식| D((비즈니스 로직 처리))

사전 설정

HTML 페이지에 다음 요소를 추가합니다:

<video id="video"></video>
<canvas id="canvas"></canvas>

JS 코드에 다음 내용을 추가하여 필요한 객체를 가져옵니다:

const videoEl = document.querySelector('#video');
const canvasEl = document.querySelector('#canvas');
const canvasCtx = canvasEl.getContext('2d');

videoEl은 video 요소로, 카메라 비디오 스트림을 video에 바인딩하여 실시간 미리보기를 제공합니다.
canvasEl은 canvas 요소입니다.
canvasCtx는 canvas의 context 2d 객체입니다.

카메라 초기화

const constraints = {
    audio: false,
    video: true,
};
navigator.mediaDevices.getUserMedia(constraints).then((stream) => {
    videoEl.srcObject = stream;
    videoEl.play();
}).catch((err) => {
    console.error(err);
    alert('카메라 열기 오류');
});

카메라 매개변수 설정
- constraints.video가 true이면 카메라 자동 선택
- constraints.video가 {facingMode: {exact: 'user'}}이면 전면 카메라 사용
- constraints.video가 {facingMode: {exact: 'environment'}}이면 후면 카메라 사용

팁

더 많은 카메라 매개변수는 카메라 설정 매개변수를 참조하세요.

카메라 이미지 캡처

canvasCtx.drawImage(videoEl, 0, 0, videoEl.offsetWidth, videoEl.offsetWidth);
const image = canvasElement.toDataURL('image/jpeg', 0.8).split('base64,').pop();

클라우드 인식 API 호출

// 클라우드 이미지 라이브러리의 Client-end URL
const clientendUrl = '클라우드 이미지 라이브러리의 Client-end URL';
// 클라우드 이미지 라이브러리의 Cloud Token
const token = '클라우드 이미지 라이브러리의 Cloud Token';
// 클라우드 이미지 라이브러리의 CRS AppId
const appId = '클라우드 이미지 라이브러리의 CRS AppId';
// image는 이전 단계에서 캡처한 이미지입니다.
const image = '/9j/4AAQSkZJRgABAQ......';

fetch(`${clientendUrl}/search`, {
    method: 'POST',
    body: `{ "image": "${image}", "appId": "${appId}", "notracking": true }`,
    headers: {
        'Content-Type': 'application/json;Charset=UTF-8',
        'Authorization': token
    }
}).then(res => res.json()).then(data => {
    console.info(data);
    // TODO: 인식 결과 처리
});

팁

네트워크 요청을 보내기 위해 fetch, XMLHttpRequest 또는 axois 라이브러리 등을 사용할 수 있습니다.

인식 결과 처리

클라우드 인식 서비스 API는 요청을 받은 후 대상이 성공적으로 인식되면 인식 결과를 반환합니다. 대상이 인식되지 않으면 미인식 상태 코드를 반환하며, 다른 오류인 경우 해당 오류 코드 및 메시지를 반환합니다.

대상 미인식

대상이 인식되지 않으면 statusCode는 17이며, 반환 결과는 다음과 같습니다:

{
  "statusCode" : 17,
  "result" : {
    "message" : "No result: there is no matching."
  },
  "date" : "2026-01-05T05:49:02.651Z",
  "timestamp" : 1767592142651
}

대상 인식

대상이 인식되면 statusCode는 0이며, 반환 결과는 다음과 같습니다:

{
  "statusCode" : 0,
  "result" : {
    "target" : {
      "targetId" : "375a4c2e********915ebc93c400",
      "allowSimilar" : "0",
      "detectableDistinctiveness" : 1,
      "detectableFeatureCount" : 3,
      "type" : "ImageTarget",
      "trackableDistinctiveness" : 0,
      "detectableFeatureDistribution" : 1,
      "trackableFeatureCount" : 3,
      "detectableRate" : 2,
      "trackableFeatureDistribution" : 1,
      "size" : "1",
      "trackablePatchContrast" : 0,
      "meta" : "eyJ2aWRlb1VybCI6Im********pL0Vhc3lBUi1NZWdhLm1wNCJ9",
      "grade" : "2",
      "trackablePatchAmbiguity" : 3,
      "name" : "Mega video",
      "appKey" : "f7ff497********f8068c",
      "trackableRate" : 2,
      "active" : "1",
      "date" : "1746609056804",
      "modified" : 1746609056804
    }
  },
  "date" : "2026-01-05T05:50:36.484Z",
  "timestamp" : 1767592236484
}

주요 필드 설명:

targetId: 대상 ID
meta: base64로 인코딩된 추가 정보, 인식 이미지 업로드 시 추가된 3D 콘텐츠 또는 비디오 URL 등
name: 대상 이름
active: "1"은 활성화 상태, "0"은 비활성화 상태

팁

전체 필드 정보는 API 참조에서 확인하세요.

비즈니스 로직 처리

meta의 정보를 사용하여 비디오 재생, 3D 모델 렌더링 등 후속 비즈니스 로직을 처리할 수 있습니다.

Table of Contents