lipla-jp 0.2.0__py3-none-any.whl

lipla/__init__.py

@@ -0,0 +1,5 @@
+"""Lipla-jpの公開API。"""
+
+from .core.license_plate_recognizer import Recognizer, Result
+
+__all__ = ["Result", "Recognizer"]

lipla/configs/characters.yml

@@ -0,0 +1,208 @@
+areas:
+  - 札幌
+  - 函館
+  - 旭川
+  - 室蘭
+  - 苫小牧
+  - 釧路
+  - 知床
+  - 帯広
+  - 十勝
+  - 北見
+  - 青森
+  - 弘前
+  - 八戸
+  - 盛岡
+  - 岩手
+  - 平泉
+  - 仙台
+  - 宮城
+  - 秋田
+  - 山形
+  - 庄内
+  - 福島
+  - 会津
+  - 郡山
+  - 白河
+  - いわき
+  - 水戸
+  - 土浦
+  - つくば
+  - 宇都宮
+  - 日光
+  - 那須
+  - とちぎ
+  - 前橋
+  - 高崎
+  - 群馬
+  - 大宮
+  - 川口
+  - 川越
+  - 所沢
+  - 熊谷
+  - 春日部
+  - 越谷
+  - 千葉
+  - 成田
+  - 市川
+  - 船橋
+  - 習志野
+  - 袖ケ浦
+  - 市原
+  - 松戸
+  - 野田
+  - 柏
+  - 品川
+  - 世田谷
+  - 練馬
+  - 杉並
+  - 板橋
+  - 足立
+  - 江東
+  - 葛飾
+  - 江戸川
+  - 八王子
+  - 多摩
+  - 横浜
+  - 川崎
+  - 湘南
+  - 相模
+  - 山梨
+  - 富士山
+  - 新潟
+  - 長岡
+  - 上越
+  - 富山
+  - 金沢
+  - 石川
+  - 福井
+  - 長野
+  - 松本
+  - 諏訪
+  - 南信州
+  - 安曇野
+  - 岐阜
+  - 飛騨
+  - 静岡
+  - 浜松
+  - 沼津
+  - 伊豆
+  - 名古屋
+  - 豊橋
+  - 岡崎
+  - 三河
+  - 豊田
+  - 一宮
+  - 尾張小牧
+  - 春日井
+  - 三重
+  - 四日市
+  - 伊勢志摩
+  - 鈴鹿
+  - 滋賀
+  - 京都
+  - 大阪
+  - なにわ
+  - 堺
+  - 和泉
+  - 神戸
+  - 姫路
+  - 奈良
+  - 飛鳥
+  - 和歌山
+  - 鳥取
+  - 島根
+  - 出雲
+  - 岡山
+  - 倉敷
+  - 広島
+  - 福山
+  - 下関
+  - 山口
+  - 徳島
+  - 高松
+  - 香川
+  - 愛媛
+  - 高知
+  - 福岡
+  - 北九州
+  - 久留米
+  - 筑豊
+  - 佐賀
+  - 長崎
+  - 佐世保
+  - 熊本
+  - 大分
+  - 宮崎
+  - 鹿児島
+  - 奄美
+  - 沖縄
+hiragana:
+  - あ
+  - い
+  - う
+  - え
+  - か
+  - き
+  - く
+  - け
+  - こ
+  - さ
+  - す
+  - せ
+  - そ
+  - た
+  - ち
+  - つ
+  - て
+  - と
+  - な
+  - に
+  - ぬ
+  - ね
+  - の
+  - は
+  - ひ
+  - ふ
+  - ほ
+  - ま
+  - み
+  - む
+  - め
+  - も
+  - や
+  - ゆ
+  - よ
+  - ら
+  - り
+  - る
+  - れ
+  - ろ
+  - わ
+  - を
+alphabet:
+  - A
+  - C
+  - F
+  - H
+  - K
+  - L
+  - M
+  - P
+  - X
+  - Y
+numbers:
+  - "0"
+  - "1"
+  - "2"
+  - "3"
+  - "4"
+  - "5"
+  - "6"
+  - "7"
+  - "8"
+  - "9"
+symbols:
+  - "-"
+  - "·"
+  - "・"

lipla/core/fixed_field_recognizer.py

@@ -0,0 +1,286 @@
+"""ナンバープレートの固定領域に特化した文字認識。"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Final, Protocol
+
+import numpy as np
+
+from lipla.inferencers.ppocr import preprocess_rec
+
+from .image_processing import validate_bgr_image
+from .ocr_result_parser import (
+    CandidateMap,
+    OCRResultParser,
+    TextCandidate,
+    create_candidate_map,
+)
+
+FIELD_RECTS: Final = {
+    "area": (0.194, 0.00, 0.519, 0.325),
+    "class_number": (0.51, 0.00, 0.81, 0.36),
+    "number": (0.15, 0.34, 1.00, 1.00),
+}
+KANA_RECTS: Final = (
+    ((0.009, 0.438, 0.197, 1.00), 1.0),
+    ((0.016, 0.469, 0.197, 1.00), 0.7),
+    ((0.000, 0.375, 0.219, 1.00), 0.7),
+)
+FIELD_FILTERS: Final = {
+    "class_number": ["numbers", "alphabet"],
+    "number": ["numbers", "symbols"],
+}
+
+
+class RecognitionSession(Protocol):
+    """文字認識セッションに必要なインターフェース。"""
+
+    def run(
+        self,
+        output_names: None,
+        input_feed: dict[str, np.ndarray],
+    ) -> list[np.ndarray]: ...
+
+
+class RecognitionDecoder(Protocol):
+    """文字認識デコーダーに必要なインターフェース。"""
+
+    character: list[str]
+
+    def decode(
+        self,
+        predictions: np.ndarray,
+        filters: Iterable[str] | None = None,
+    ) -> tuple[str, float]: ...
+
+
+class RecognitionModel(Protocol):
+    """固定領域OCRに必要なモデルインターフェース。"""
+
+    rec_session: RecognitionSession
+    rec_input_name: str
+    rec_target_height: int
+    decoder: RecognitionDecoder
+
+
+def logsumexp(values: np.ndarray) -> float:
+    """オーバーフローを避けながら指数の和の対数を計算する。
+
+    Args:
+        values: 対数空間の値。
+
+    Returns:
+        ``log(sum(exp(values)))`` の計算結果。
+    """
+    maximum = float(np.max(values))
+    if not np.isfinite(maximum):
+        return -np.inf
+    return maximum + float(np.log(np.exp(values - maximum).sum()))
+
+
+def ctc_log_probability(
+    log_probabilities: np.ndarray, tokens: tuple[int, ...]
+) -> float:
+    """1つの語彙に対するCTC前向き確率を対数空間で計算する。
+
+    Args:
+        log_probabilities: 各時刻・各文字の対数確率。Blankは添字0とする。
+        tokens: 評価する文字列の文字インデックス。
+
+    Returns:
+        指定した文字列を生成する全CTCパスの対数確率。
+
+    Raises:
+        ValueError: ``tokens`` が空、または時間ステップが不足している場合。
+    """
+    if not tokens:
+        raise ValueError("tokens must not be empty")
+    if len(log_probabilities) == 0:
+        raise ValueError("log_probabilities must contain at least one timestep")
+
+    extended = [0]
+    for token in tokens:
+        extended.extend((token, 0))
+
+    previous = np.full(len(extended), -np.inf, dtype=np.float64)
+    previous[0] = log_probabilities[0, 0]
+    previous[1] = log_probabilities[0, extended[1]]
+    for timestep in range(1, len(log_probabilities)):
+        current = np.full_like(previous, -np.inf)
+        for state, token in enumerate(extended):
+            incoming = [previous[state]]
+            if state > 0:
+                incoming.append(previous[state - 1])
+            if state > 1 and token != 0 and token != extended[state - 2]:
+                incoming.append(previous[state - 2])
+            current[state] = logsumexp(np.asarray(incoming))
+            current[state] += log_probabilities[timestep, token]
+        previous = current
+    return logsumexp(previous[-2:])
+
+
+class FixedFieldRecognizer:
+    """プレートの既知レイアウトから4項目を個別認識する。
+
+    Args:
+        ocr_model: PP-OCRの文字認識セッションとデコーダーを持つオブジェクト。
+        parser: 地名とひらがなの語彙を保持するOCR結果パーサー。
+    """
+
+    def __init__(self, ocr_model: RecognitionModel, parser: OCRResultParser) -> None:
+        self.ocr_model = ocr_model
+        self.parser = parser
+        decoder_characters = self.ocr_model.decoder.character
+        self.area_tokens = tuple(
+            (
+                area,
+                tuple(decoder_characters.index(character) for character in area),
+            )
+            for area in parser.areas
+        )
+
+    def recognize(self, image: np.ndarray) -> CandidateMap:
+        """固定領域を切り出して項目別の文字列候補を生成する。
+
+        必要な文字認識インターフェースをOCRモデルが持たない場合は、全項目が
+        空の候補辞書を返す。これにより、文字検出だけを実装した差し替えモデル
+        でも空間OCR解析を利用できる。
+
+        Args:
+            image: 射影・色補正済みのBGRプレート画像。
+
+        Returns:
+            項目別の文字列候補。
+
+        Raises:
+            TypeError: 画像の型またはデータ型が不正な場合。
+            ValueError: 画像が空、またはBGR画像ではない場合。
+        """
+        validate_bgr_image(image)
+        candidates = create_candidate_map()
+        required = (
+            "rec_session",
+            "rec_input_name",
+            "rec_target_height",
+            "decoder",
+        )
+        if not all(hasattr(self.ocr_model, name) for name in required):
+            return candidates
+
+        height, width = image.shape[:2]
+        for field_name, rect in FIELD_RECTS.items():
+            crop = self._crop(image, rect)
+            if field_name == "area":
+                candidate = self._recognize_area(crop)
+            elif field_name == "class_number":
+                candidate = self._recognize_class_number(crop)
+            else:
+                candidate = self._recognize_crop(crop, FIELD_FILTERS[field_name])
+            if candidate.text:
+                candidates[field_name].append(candidate)
+
+        kana_candidate = self._recognize_kana(image)
+        if kana_candidate.text:
+            candidates["kana"].append(kana_candidate)
+
+        top_row = image[
+            : max(1, int(round(height * 0.41))),
+            int(round(width * 0.14)) : int(round(width * 0.85)),
+        ]
+        self.parser.split_top_text(self._recognize_crop(top_row, None), candidates)
+        return candidates
+
+    @staticmethod
+    def _crop(image: np.ndarray, rect: tuple[float, float, float, float]) -> np.ndarray:
+        height, width = image.shape[:2]
+        x1, y1, x2, y2 = rect
+        left = max(0, min(width - 1, int(round(x1 * width))))
+        top = max(0, min(height - 1, int(round(y1 * height))))
+        right = max(left + 1, min(width, int(round(x2 * width))))
+        bottom = max(top + 1, min(height, int(round(y2 * height))))
+        return image[top:bottom, left:right]
+
+    def _recognize_crop(
+        self, crop: np.ndarray, filters: list[str] | None
+    ) -> TextCandidate:
+        if crop.size == 0:
+            return TextCandidate("", 0.0)
+        rec_input = preprocess_rec(crop, target_height=self.ocr_model.rec_target_height)
+        rec_outputs = self.ocr_model.rec_session.run(
+            None, {self.ocr_model.rec_input_name: rec_input}
+        )
+        text, score = self.ocr_model.decoder.decode(rec_outputs[0], filters=filters)
+        return TextCandidate(str(text).strip(), float(score))
+
+    def _recognize_area(self, crop: np.ndarray) -> TextCandidate:
+        if crop.size == 0:
+            return TextCandidate("", 0.0)
+        rec_input = preprocess_rec(crop, target_height=self.ocr_model.rec_target_height)
+        rec_outputs = self.ocr_model.rec_session.run(
+            None, {self.ocr_model.rec_input_name: rec_input}
+        )[0]
+        probabilities = np.asarray(rec_outputs, dtype=np.float64)[0]
+        log_probabilities = np.log(np.clip(probabilities, 1e-30, 1.0))
+        scores = np.asarray(
+            [
+                ctc_log_probability(log_probabilities, tokens) / len(tokens)
+                for _, tokens in self.area_tokens
+            ],
+            dtype=np.float64,
+        )
+        best_index = int(np.argmax(scores))
+        normalizer = logsumexp(scores)
+        confidence = float(np.exp(scores[best_index] - normalizer))
+        return TextCandidate(self.area_tokens[best_index][0], confidence)
+
+    def _recognize_class_number(self, crop: np.ndarray) -> TextCandidate:
+        if crop.size == 0:
+            return TextCandidate("", 0.0)
+        rec_input = preprocess_rec(crop, target_height=self.ocr_model.rec_target_height)
+        rec_outputs = self.ocr_model.rec_session.run(
+            None, {self.ocr_model.rec_input_name: rec_input}
+        )[0]
+        text, score = self.ocr_model.decoder.decode(
+            rec_outputs, filters=FIELD_FILTERS["class_number"]
+        )
+        return TextCandidate(str(text).strip().upper(), float(score))
+
+    def _single_character_scores(
+        self, crop: np.ndarray, allowed_characters: Iterable[str]
+    ) -> dict[str, float]:
+        if crop.size == 0:
+            return {}
+        rec_input = preprocess_rec(crop, target_height=self.ocr_model.rec_target_height)
+        rec_outputs = self.ocr_model.rec_session.run(
+            None, {self.ocr_model.rec_input_name: rec_input}
+        )[0]
+        probabilities = np.asarray(rec_outputs)[0]
+        character_indices = {
+            character: self.ocr_model.decoder.character.index(character)
+            for character in allowed_characters
+            if character in self.ocr_model.decoder.character
+        }
+        return {
+            character: max(0.0, float(np.max(probabilities[:, index])))
+            for character, index in character_indices.items()
+        }
+
+    def _recognize_kana(self, image: np.ndarray) -> TextCandidate:
+        combined = {character: 0.0 for character in self.parser.kana_characters}
+        for rect, weight in KANA_RECTS:
+            scores = self._single_character_scores(
+                self._crop(image, rect), self.parser.kana_characters
+            )
+            score_sum = sum(scores.values())
+            if score_sum <= 0.0:
+                continue
+            for character, score in scores.items():
+                combined[character] += weight * score / score_sum
+
+        if not combined:
+            return TextCandidate("", 0.0)
+        character = max(combined, key=combined.get)
+        score_sum = sum(combined.values())
+        confidence = combined[character] / score_sum if score_sum > 0.0 else 0.0
+        return TextCandidate(character, float(confidence))

lipla/core/image_processing.py

@@ -0,0 +1,164 @@
+"""ナンバープレート認識で使用する画像の検証と前処理。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+LOCAL_BLACK_VALUE_MAX = 50
+LOCAL_GREEN_HUE_MIN = 30
+LOCAL_GREEN_HUE_MAX = 95
+LOCAL_GREEN_SATURATION_MIN = 25
+LOCAL_GREEN_VALUE_MAX = 130
+
+
+def validate_bgr_image(image: np.ndarray) -> None:
+    """BGR画像として利用できる配列か検証する。
+
+    Args:
+        image: 検証対象の画像。
+
+    Raises:
+        TypeError: ``image`` が ``numpy.ndarray`` ではない場合、または
+            データ型が ``uint8`` ではない場合。
+        ValueError: ``image`` が空、または形状が ``(H, W, 3)`` ではない場合。
+    """
+    if not isinstance(image, np.ndarray):
+        raise TypeError("image must be a numpy.ndarray")
+    if image.ndim != 3 or image.shape[2] != 3:
+        raise ValueError("image must be a BGR image with shape (H, W, 3)")
+    if image.shape[0] == 0 or image.shape[1] == 0:
+        raise ValueError("image must not be empty")
+    if image.dtype != np.uint8:
+        raise TypeError("image must have dtype uint8")
+
+
+def read_bgr_image(path: str | Path) -> np.ndarray:
+    """ファイルパスからBGR画像を読み込む。
+
+    OpenCVのパス処理に依存せずバイト列を復号するため、日本語を含むパスも
+    使用できる。
+
+    Args:
+        path: 読み込む画像ファイルのパス。
+
+    Returns:
+        ``uint8`` のBGR画像。
+
+    Raises:
+        OSError: ファイルを読み込めない場合。
+        ValueError: ファイルを画像として復号できない場合。
+    """
+    image_path = Path(path)
+    encoded = np.frombuffer(image_path.read_bytes(), dtype=np.uint8)
+    image = cv2.imdecode(encoded, cv2.IMREAD_COLOR) if encoded.size > 0 else None
+    if image is None:
+        raise ValueError(f"Could not decode image file: {image_path}")
+    return image
+
+
+def as_bgr(image: np.ndarray) -> np.ndarray:
+    """正規化後の画像をBGR形式へ揃える。
+
+    Args:
+        image: グレースケール画像、またはBGR画像。
+
+    Returns:
+        BGR形式の画像。入力がBGRの場合は同じ配列を返す。
+
+    Raises:
+        TypeError: 入力が配列ではない場合、またはデータ型が ``uint8`` では
+            ない場合。
+        ValueError: 入力が空、または対応していない形状の場合。
+    """
+    if not isinstance(image, np.ndarray):
+        raise TypeError("normalized image must be a numpy.ndarray")
+    if image.ndim == 2:
+        if image.size == 0:
+            raise ValueError("normalized image must not be empty")
+        if image.dtype != np.uint8:
+            raise TypeError("normalized image must have dtype uint8")
+        return cv2.cvtColor(image, cv2.COLOR_GRAY2BGR)
+    if image.ndim == 3 and image.shape[2] == 3:
+        validate_bgr_image(image)
+        return image
+    raise ValueError(f"normalized image has an invalid shape: {image.shape}")
+
+
+def preprocess_local_plate(image: np.ndarray) -> np.ndarray:
+    """図柄入りナンバープレートから文字色以外を白くする。
+
+    黒色から濃緑色までの画素を残し、OCRを妨げる背景の図柄を除去する。
+
+    Args:
+        image: ``uint8`` のBGR画像。
+
+    Returns:
+        背景の図柄を白色に置換したBGR画像。
+
+    Raises:
+        TypeError: 画像の型またはデータ型が不正な場合。
+        ValueError: 画像が空、またはBGR画像ではない場合。
+    """
+    validate_bgr_image(image)
+    hsv = cv2.cvtColor(image, cv2.COLOR_BGR2HSV)
+    hue, saturation, value = cv2.split(hsv)
+    black = value <= LOCAL_BLACK_VALUE_MAX
+    dark_green = (
+        (hue >= LOCAL_GREEN_HUE_MIN)
+        & (hue <= LOCAL_GREEN_HUE_MAX)
+        & (saturation >= LOCAL_GREEN_SATURATION_MIN)
+        & (value <= LOCAL_GREEN_VALUE_MAX)
+    )
+    filtered = np.full_like(image, 255)
+    keep = black | dark_green
+    filtered[keep] = image[keep]
+    return filtered
+
+
+def pad_for_ocr(image: np.ndarray) -> tuple[np.ndarray, int]:
+    """OCRの文字検出用に画像の周囲へ余白を追加する。
+
+    Args:
+        image: 余白を追加するBGR画像。
+
+    Returns:
+        余白を追加した画像と、上下左右に追加したピクセル数。
+
+    Raises:
+        TypeError: 画像の型またはデータ型が不正な場合。
+        ValueError: 画像が空、またはBGR画像ではない場合。
+    """
+    validate_bgr_image(image)
+    padding = max(8, int(round(image.shape[0] * 0.10)))
+    padded = cv2.copyMakeBorder(
+        image,
+        padding,
+        padding,
+        padding,
+        padding,
+        cv2.BORDER_CONSTANT,
+        value=(127, 127, 127),
+    )
+    return padded, padding
+
+
+def remove_padding(image: np.ndarray, padding: int) -> np.ndarray:
+    """画像から上下左右の余白を取り除く。
+
+    余白がゼロ以下、または画像に対して大きすぎる場合は入力をそのまま返す。
+
+    Args:
+        image: 余白を含む画像。
+        padding: 上下左右から取り除くピクセル数。
+
+    Returns:
+        余白を取り除いた画像、または元の画像。
+    """
+    if padding <= 0:
+        return image
+    if image.shape[0] <= padding * 2 or image.shape[1] <= padding * 2:
+        return image
+    return image[padding:-padding, padding:-padding]