English 日本語 한국어 Tiếng Việt

응용 프로그램 개발 가이드

목차

1. 엔트리 포인트

모든 함수 원형은 아래와 같습니다.

#ifdef WIN32
#define TS_ANPR_ENTRY extern "C" __declspec(dllexport) const char* WINAPI
#else
#define TS_ANPR_ENTRY extern "C" const char*
#endif

장황해지지 않도록 이하는 TS_ANPR_ENTRY로 표기합니다.

1.1. anpr_initialize

라이브러리를 초기화 합니다. 라이브러리를 사용하기 위해 다른 함수보다 먼저 한 번 호출해야 합니다.

TS_ANPR_ENTRY anpr_initialize(const char* mode); // [IN] 라이브러리 동작 방식 설정

Parameters:

Return value:

1.2. anpr_read_file

이미지 파일에서 차량 번호를 인식합니다.

TS_ANPR_ENTRY anpr_read_file(
  const char* imgFileName,  // [IN] 입력 이미지 파일명
  const char* outputFormat, // [IN] 출력 데이터 형식
  const char* options);     // [IN] 기능 옵션

Parameters:

Return value:

Remarks:

1.3. anpr_read_pixels

로딩된 이미지의 메모리 버퍼에서 차량 번호를 인식합니다. TS-ANPR v2.3.0부터는 인코딩된 이미지를 지원합니다.

TS_ANPR_ENTRY anpr_read_pixels(
  const unsigned char* pixels,  // [IN] 이미지 픽셀 시작 주소
  const unsigned long width,    // [IN] 이미지 가로 픽셀 수
  const unsigned long height,   // [IN] 이미지 세로 픽셀 수
  const long stride,            // [IN] 이미지 한 라인의 바이트 수
  const char* pixelFormat,      // [IN] 이미지 픽셀 형식
  const char* outputFormat,     // [IN] 출력 데이터 형식
  const char* options);         // [IN] 기능 옵션

Parameters:

Return value: (anpr_read_file과 동일) Remarks: (anpr_read_file과 동일)

  # 파이썬 예제

  # 비디오 프레임을 입력
  ret, frame = capture.read()
  height = frame.shape[0]
  width = frame.shape[1]
  result = anpr_read_pixels(bytes(frame), width, height, 0, b'BGR', b'json', b'vms')
  if len(result) > 0:
      print(result.decode('utf8'))

  # 웹사이트의 이미지를 입력
  response = requests.get('https://example.com/image.jpg')
  if response.status_code == 200:
      result = anpr_read_pixels(response.content, 0, 0, 0, b'encoded', b'json', b'vms')
      if len(result) > 0:
          print(result.decode('utf8'))

2. 인식 옵션

2.1. 라이선스별 지원 옵션 목록

문자 의미 적용 라이선스
v 번호판 차량 부착 여부 판단 전체
b 번호판 오토바이 부착 여부 판단 (베트남 번호판 전용) 전체
m 여러 대의 차량 번호판을 모두 인식 (다중 인식) 객체인식, Pro, Server
s 360° 모든 각도의 차량에서 번호판 인식 (서라운드 인식) 객체인식, Pro, Server
d 객체 인식 (만.공차용) 전체
r 인식된 객체(차량)의 차량 번호 인식 전체
i 관심 영역(RoI) 설정 전체
x 비관심 영역(RoU) 설정 전체
a 최소 차량 번호판 크기 설정 전체

2.2. 옵션 선택 안내

아래 플로우차트에서 시작에서 선택완료까지 조건을 따라 이동하면서 지나간 초록색 원의 문자들을 모아 옵션 값으로 사용하면 됩니다. (문자의 순서는 무관합니다.) 예) 이동 경로가 시작 → v → s → m → 선택완료 이면 "vsm"가 옵션 값입니다.

flowchart TD

  start[/시작/]-->attach
  attach-->|상관없음|multi
  attach-->|차량에 부착된 번호판만|v((v)):::opt

  v-->angle
  angle-->|바로 선 차량만|multi
  angle-->|360° 모든 각도|s((s)):::opt
  s-->multi
  multi-->|예|m((m)):::opt
  multi-->|아니오|done[/선택완료/]
  m-->done

  start-->d((d)):::opt
  d-->angle2
  angle2-->|바로 선 차량만|multi2
  angle2-->|360° 모든 각도|s2((s)):::opt
  s2-->multi2
  multi2-->|예|m2((m)):::opt
  multi2-->|아니오|read
  m2-->read

  read-->|예|r((r)):::opt
  read-->|아니오|done
  r-->done


  subgraph "번호 인식"
    attach
    v
    angle
    multi
    m
    s
  end

  subgraph "객체 인식"
    read
    angle2
    multi2
    s2
    m2
    d
    r
  end

  classDef opt fill:#6F6,stroke:#CCC,stroke-width:4px,padding:10px,font-weight:bold

2.3. 관심 영역(RoI) / 비관심 영역(RoU) 설정

관심 영역(RoI)

비관심 영역(RoU)

[참고] 관심 영역 또는 비관심 영역을 모두 지정하지 않으면 전체 이미지에서 번호 인식을 합니다. 관심 영역과 비관심 영역을 모두 지정할 경우 겹치는 구간이 있으면 비관심 영역을 우선합니다. 따라서 겹치는 구간의 차량 번호판은 모두 무시됩니다.

# 파이썬 예제
# 위 이미지에서 각 다각형 영역의 각 꼭지점 픽셀 좌표가 아래와 같은 때
# RoI = [(810,64), (939,1182), (1486,1182), (1149,571), (879,124), (839,64)]
# RoI2 = [(771,67), (479,1182), (1793,1182), (801,67)]
# RoU = [(851,70), (923,134), (1753,1182), (1789,1182), (1789,250), (1176,87), (946,68)]

# 관심 영역 한 개 설정
result = anpr_read_file(
  b'roi.jpg',    # 입력 파일명
  b'text',       # 출력 형식
  b'vi810,64,939,1182,1486,1182,1149,571,879,124,839,64') # 차량에 부착된 번호판만 인식하기 위해 v 옵션 사용

# 관심 영역 두 개 설정
result = anpr_read_file(
  b'roi.jpg',    # 입력 파일명
  b'text',       # 출력 형식
  b'vi810,64,939,1182,1486,1182,1149,571,879,124,839,64i771,67,479,1182,1793,1182,801,67')

# 관심 영역 한 개와 비관심 영역 한 개 설정
result = anpr_read_file(
  b'roi.jpg',    # 입력 파일명
  b'text',       # 출력 형식
  b'vi810,64,939,1182,1486,1182,1149,571,879,124,839,64x851,70,923,134,1753,1182,1789,1182,1789,250,1176,87,946,68')

# 비관심 영역 한 개 설정
result = anpr_read_file(
  b'roi.jpg',    # 입력 파일명
  b'text',       # 출력 형식
  b'vx851,70,923,134,1753,1182,1789,1182,1789,250,1176,87,946,68')

2.4. 최소 번호판 크기 설정

3. 출력 데이터 형식

출력 데이터는 options에 d가 포함되는 객체 인식과 포함되지 않는 차량 번호 인식 두 가지 형식으로 구분됩니다.

3.1. 차량 번호 인식 결과

3.1.1. text

차량 번호 텍스트만 출력합니다. 번호판이 여러 개인 경우는 줄바꿈 문자 CR (0x0d)로 구분합니다.

01가2345
67나8901

차량 번호가 인식되지 않은 경우는 빈 텍스트NULL terminated string (0x00)를 출력합니다.

오류가 반환되는 경우는 아래와 같은 텍스트 형식으로 출력합니다.

error: (1) Invalid parameters
3.1.2. csv

차량 번호와 속성을 csv 형식으로 출력합니다. 인식된 차량 번호 당 한 라인 씩으로 구성되며 각 컬럼은 콤마 문자(,)로 구분됩니다.

01가2345,1217,2083,92,175,12.45,0.75,0.83,0.20,ev
67나8901,1108,1317,67,217,12.45,0.76,0.89,0.10,

각 컬럼의 의미는 다음과 같습니다. | 컬럼 | 의미 | 비고 |—–:|—————————|———————— | 1 | 차량번호 | text | 2 | 번호판 좌측 상단 x 좌표 | area.x | 3 | 번호판 좌측 상단 y 좌표 | area.y | 4 | 번호판 폭 | area.width | 5 | 번호판 높이 | area.height | 6 | 번호판 각도 | area.angle | 7 | 문자 인식 신뢰도 | conf.ocr | 8 | 번호판 인식 신뢰도 | conf.plate | 9 | 문자 인식 소요 시간 (초) | elapsed | 10(1) | 친환경 전기자동차 여부 | attr.ev

차량 번호가 인식되지 않은 경우는 빈 텍스트NULL terminated string (0x00)를 출력합니다.

오류가 반환되는 경우는 아래와 같은 텍스트 형식으로 출력합니다.

error,1,Invalid parameters

3.1.3. json

차량 번호와 속성을 json 형식으로 출력합니다.

[
  {
    // 첫번째 번호판
    text: "01가2345", // 차량 번호
    area: {
      // 번호판 영역 (픽셀 단위)
      x: 1217, // 좌측 상단 x 좌표
      y: 2083, // 좌측 상단 y 좌표
      width: 92, // 폭
      height: 175, // 높이
      angle: 12.45, // 기울기 (도)
    },
    attrs: {
      // 번호판 속성
      ev: true, // 친환경 전기자동차 여부
    },
    ev: true, // deprecated (attrs.ev로 옮김, 추후 버전에서 삭제 예정)
    conf: {
      // 신뢰도 (범위: 0 ~ 1)
      ocr: 0.75, // 문자 인식 신뢰도
      plate: 0.84, // 번호판 인식 신뢰도
    },
    elapsed: 0.27, // 소요 시간 (초 단위)
  },
  {
    // 두번째 번호판
    text: "67나8901",
    area: {
      x: 1108,
      y: 1317,
      width: 67,
      height: 217,
      angle: 12.45,
    },
    attrs: {
      ev: false,
    },
    ev: false,
    conf: {
      ocr: 0.76,
      plate: 0.89,
    },
    elapsed: 0.14,
  },
];

차량 번호가 인식되지 않은 경우는 아래와 같이 빈 데이터를 출력합니다.

[];

오류가 반환되는 경우는 아래와 같은 json 형식으로 출력합니다.

{
  "error": {
    "code": 1,
    "message": "Invalid parameters"
  }
}

3.1.4. yaml

차량 번호와 속성을 yaml 형식으로 출력합니다.

- text: 01가2345 # 첫번째 번호판, 차량 번호
  area: # 번호판 영역 (픽셀 단위)
    x: 1217 # 좌측 상단 x 좌표
    y: 2083 # 좌측 상단 y 좌표
    width: 92 # 폭
    height: 175 # 높이
    angle: 12.45 # 기울기 (도)
  conf: # 신뢰도 (범위: 0 ~ 1)
    ocr: 0.75 # 문자 인식 신뢰도
    plate: 0.83 # 번호판 인식 신뢰도
  attrs: # 번호판 속성
    ev: true # 친환경 전기자동차 여부
  ev: true # deprecated (attrs.ev로 옮김, 추후 버전에서 삭제 예정)
  elapsed: 0.20 # 소요 시간 (초)
- text: 67나8901 # 두번째 번호판
  area:
    x: 1108
    y: 1317
    width: 67
    height: 217
    angle: 12.45
  conf:
    ocr: 0.76
    plate: 0.89
  ev: false
  elapsed: 0.10

차량 번호가 인식되지 않은 경우는 아래와 같이 빈 데이터를 출력합니다.

오류가 반환되는 경우는 아래와 같은 yaml 형식으로 출력합니다.

error
  code: 1
  message: Invalid parameters

3.1.5. xml

차량 번호와 속성을 xml 형식으로 출력합니다.

<?xml version="1.0" encoding="utf-8"?>
<data>
  <!-- 첫번째 번호판
    text: 차량 번호
    ev: deprecated (attrs.ev로 옮김, 추후 버전에서 삭제 예정)
    elapsed: 소요 시간 (초)
  -->
  <license-plate text="01가2345" ev="true" elapsed="0.20">
    <!-- 번호판 속성
      ev: 친환경 전기자동차 여부
    -->
    <attrs ev="true"/>
    <!-- 번호판 영역 (픽셀 단위)
      x: 좌측 상단 x 좌표
      y:  좌측 상단 y 좌표
      width: 폭
      height: 높이
      angle: 기울기 (도)
    -->
    <area x="1217" y="2083" width="92" height="175" angle="12.45"/>
    <!-- 신뢰도 (범위: 0 ~ 1)
      ocr: 문자 인식 신뢰도
      plate: 번호판 인식 신뢰도
    -->
    <conf ocr="0.75" plate="0.83"/>
  </license-plate>
  <!-- 두번째 번호판 -->
  <license-plate text="67나8901" ev="false" elapsed="0.11">
    <attrs ev="false"/>
    <area x="1108" y="1317" width="67" height="217"/>
    <conf ocr="0.76" plate="0.89"/>
  </license-plate>
</data>

차량 번호가 인식되지 않은 경우는 아래와 같이 빈 데이터를 출력합니다.

<?xml version="1.0" encoding="utf-8"?>
<data />

오류가 반환되는 경우는 아래와 같은 xml 형식으로 출력합니다.

<?xml version="1.0" encoding="utf-8"?>
<error code="1" message="Invalid parameters" />

3.2. 객체 인식 결과

이미지에서 미리 학습한 객체를 찾아냅니다. 차별화된 특징은 360° 어안 렌즈 카메라로 촬영된 원본 이미지에서 외곡된 형태의 객체를 인식합니다. 현재 지원하는 객체 목록은 아래와 같습니다. | class | 이름
|————–|———————————- | car | 차량 | motorcycle | 오토바이

3.2.1. csv, text

객체 인식 결과를 cvs 형식의 텍스트로 출력합니다. 출력 형식을 text로 지정한 경우도 csv 형식으로 대체되어 출력됩니다.

인식된 객체 당 한 라인 씩으로 구성되며 각 컬럼은 콤마 문자(,)로 구분됩니다.

car,2171,2281,396,521,0.9679,0.2886,51조8969,2420,2295,110,81,147.5933,0.9005,0.7864,0.3913,ev
car,264,2266,433,543,0.9706,0.2886,41노7656,315,2281,103,81,211.3135,0.9160,0.8299,0.4189,
car,777,0,579,403,0.9716,0.2886 // 번호판 정보가 없는 경우

각 컬럼의 의미는 다음과 같습니다. | 컬럼 | 의미 | 비고 |—–:|———————————–|———————— | 1 | 종류 | class | 2 | 번호판 좌측 상단 x 좌표 | area.x | 3 | 번호판 좌측 상단 y 좌표 | area.y | 4 | 폭 | area.width | 5 | 높이 | area.height | 6 | 신뢰도 | conf | 7 | 소요 시간(초) | elapsed | 8(1) | 차량번호 | licensePlate.text | 9 | 번호판 x픽셀 좌표 | licensePlate.area.x | 10 | 번호판 y픽셀 좌표 | licensePlate.area.y | 11 | 번호판 폭 | licensePlate.area.width | 12 | 번호판 높이 | licensePlate.area.height | 13 | 번호판 각도 | licensePlate.area.angle | 14 | 문자 인식 신뢰도 | licensePlate.conf.ocr | 15 | 번호판 인식 신뢰도 | licensePlate.conf.plate | 16 | 문자 인식 소요 시간 (초) | licensePlate.elapsed | 17(2) | 친환경 전기자동차 여부 | licensePlate.attrs.ev

객체가 인식되지 않은 경우는 빈 텍스트NULL terminated string (0x00)를 출력합니다.

오류가 반환되는 경우는 아래와 같은 텍스트 형식으로 출력합니다.

error,1,Invalid parameters
3.2.2. json

객체 인식 결과를 json 형식으로 출력합니다.

 [
  {                           // 첫번째 객체
    "class": "car",           // 객체 종류
    "area": {                 // 객체 영역 (픽셀 단위)
      "x": 2171,              // 좌측 상단 x 좌표
      "y": 2281,              // 좌측 상단 y 좌표
      "width": 396,           // 폭
      "height": 521           // 높이
    },
    "conf": 0.9679,           // 객체 인식 신뢰도 (범위: 0 ~ 1)
    "elapsed": 0.2513,        // 소요 시간 (초)
    "licensePlate": [         // 번호판
      {
        "text": "51조8969"    // 차량 번호
        "area": {             // 번호판 영역 (픽셀 단위)
          "x": 2420,          // 좌측 상단 x 좌표
          "y": 2295           // 좌측 상단 y 좌표
          "width": 110,       // 폭
          "height": 81,       // 높이
          "angle": 147.5933   // 기울기 (도)
        },
        "attrs": {            // 번호판 속성
          "ev": true          // 친환경 전기자동차 여부
        },
        "conf": {             // 신뢰도 (범위: 0 ~ 1)
          "ocr": 0.9005,      // 문자 인식 신뢰도
          "plate": 0.7864     // 번호판 인식 신뢰도
        },
        "elapsed": 0.3525,    // 소요 시간 (초)
      }
    ]
  },
  {                           // 두번째 객체
    "class": "car",
    "area": {
      "x": 264,
      "y": 2266,
      "width": 433,
      "height": 543
    },
    "conf": 0.9706,
    "elapsed": 0.2513,
    "licensePlate": [
      {
        "text": "41노7656"
        "area": {
          "x": 315,
          "y": 2281,
          "width": 103,
          "height": 81,
          "angle": 211.3135
        },
        "attrs": {
          "ev": false
        },
        "conf": {
          "ocr": 0.916,
          "plate": 0.8299
        },
        "elapsed": 0.4402
      }
    ]
  },
  {                           // 세번째 객체 (번호판 정보가 없는 경우)
    "class": "car",
    "area": {
      "x": 777,
      "y": 0
      "height": 403,
      "width": 579,
    },
    "conf": 0.9716,
    "elapsed": 0.2513
  }
]

객체가 인식되지 않은 경우는 아래와 같이 빈 데이터를 출력합니다.

[];

오류가 반환되는 경우는 아래와 같은 json 형식으로 출력합니다.

{
  "error": {
    "code": 1,
    "message": "Invalid parameters"
  }
}
3.2.3. yaml

객체 인식 결과를 yaml 형식으로 출력합니다.

- class: car # 첫번째 객체, 객체 종류
  area: # 객체 영역 (픽셀 단위)
    x: 2171 # 좌측 상단 x 좌표
    y: 2281 # 좌측 상단 y 좌표
    width: 396 # 폭
    height: 521 # 높이
  conf: 0.9678 # 객체 인식 신뢰도 (범위: 0 ~ 1)
  elapsed: 0.3190 # 소요 시간 (초)
  licensePlate: # 번호판
    - text: 51조8969 # 차량 번호
      area: # 번호판 영역 (픽셀 단위)
        x: 2420 # 좌측 상단 x 좌표
        y: 2295 # 좌측 상단 y 좌표
        width: 110 # 폭
        height: 81 # 높이
        angle: 147.5933 # 기울기 (도)
      attrs: # 번호판 속성
        ev: true # 친환경 전기자동차 여부
      conf: # 신뢰도 (범위: 0 ~ 1)
        ocr: 0.9005 # 문자 인식 신뢰도
        plate: 0.7864 # 번호판 인식 신뢰도
      elapsed: 0.3226 # 소요 시간 (초)
- class: car # 두번째 객체
  area:
    x: 264
    y: 2266
    width: 433
    height: 543
  conf: 0.9706
  elapsed: 0.3191
  licensePlate:
    - text: 41노7656
      area:
        x: 315
        y: 2281
        width: 103
        height: 81
        angle: 211.3135
      conf:
        ocr: 0.916
        plate: 0.8299
      attrs:
        ev: false
      elapsed: 0.5527
- class: car # 세번째 객체 (번호판 정보가 없는 경우)
  area:
    x: 777
    y: 0
    width: 579
    height: 403
  conf: 0.9716
  elapsed: 0.3191

객체가 인식되지 않은 경우는 아래와 같이 빈 데이터를 출력합니다.

오류가 반환되는 경우는 아래와 같은 yaml 형식으로 출력합니다.

error
  code: 1
  message: Invalid parameters
3.2.4. xml

객체 인식 결과를 xml 형식으로 출력합니다.

<?xml version="1.0" encoding="utf-8"?>
<data>
  <!-- 첫번째 객체
    class: 객체 종류
    conf: 객체 인식 신뢰도 (범위: 0 ~ 1)
    elapsed: 소요 시간 (초)
  -->
  <object class="car" conf="0.9679" elapsed="0.3287">
    <!-- 객체 영역 (픽셀 단위)
      x: 좌측 상단 x 좌표
      y: 좌측 상단 y 좌표
      width: 폭
      height: 높이
    -->
    <area x="2171" y="2281" width="396" height="521"/>

    <!-- 번호판
      text: 차량 번호
      elapsed: 소요 시간 (초)
    -->
    <license-plate text="51조8969" elapsed="0.3961">

      <!-- 번호판 속성
        ev: 친환경 전기자동차 여부
      -->
      <attrs ev="true"/>

      <!-- 번호판 영역 (픽셀 단위)
        x: 좌측 상단 x 좌표
        y: 좌측 상단 y 좌표
        width: 폭
        height: 높이
        angle: 기울기 (도)
      -->
      <area x="2420" y="2295" width="110" height="81" angle="147.5933"/>

      <!-- 신뢰도 (범위: 0 ~ 1)
        ocr: 문자 인식 신뢰도
        plate: 번호판 인식 신뢰도
      -->
      <conf ocr="0.9005" plate="0.7864"/>
    </license-plate>
  </object>

  <!-- 두번째 객체 -->
  <object class="car" conf="0.9706" elapsed="0.3287">
    <area x="264" y="2266" width="433" height="543"/>
    <license-plate text="41노7656" elapsed="0.4364">
      <attrs ev="false"/>
      <area x="315" y="2281" width="103" height="81" angle="211.3135"/>
      <conf ocr="0.9160" plate="0.8299"/>
    </license-plate>
  </object>

  <!-- 세번째 객체 (번호판 정보가 없는 경우) -->
  <object class="car" conf="0.9716" elapsed="0.3287">
    <area x="777" y="0" width="579" height="403"/>
  </object>
</data>

객체가 인식되지 않은 경우는 아래와 같이 빈 데이터를 출력합니다.

<?xml version="1.0" encoding="utf-8"?>
<data />

오류가 반환되는 경우는 아래와 같은 xml 형식으로 출력합니다.

<?xml version="1.0" encoding="utf-8"?>
<error code="1" message="Invalid parameters" />

4. 오류 코드표

전체 오류 목록은 아래 표와 같습니다.

code message 설명
1 Invalid parameters 함수 호출 인자가 잘못된 경우
2 File not found 입력 이미지 파일이 존재하지 않는 경우
3 Invalid image 입력 이미지 메모리가 형식에 맞지 않는 경우
4 Unsupported image format 입력 이미지가 지원되지 않는 형식인 경우
100 License expired 라이선스가 만료된 경우
101 Corrupted library 라이브러리 구성 파일 중 일부가 없거나 손상된 경우
102 Not initialized 엔진이 초기화되지 않은 상태
103 Too many workers 라이브러리 호출 쓰레드 수가 한계를 초과한 경우 (최대 256개)
104 Resource exhausted 더 이상 자원을 할당할 수 없는 경우
105 License not installed 라이선스가 설치되지 않은 상태 (리눅스에서 무료 평가판 라이센스가 설치되지 않은 경우 발생함)
106 USB dongle I/O error USB 라이선스 동글 읽기 실패시 발생
107 License required 해당 기능을 사용하기 위한 라이선스가 없음
108 Unsupported platform 지원되지 않는 환경에서 실행시 발생
200 Unknown 기타 정의되지 않은 오류