kotoha 0.1.0__py3-none-any.whl

kotoha/__init__.py

@@ -0,0 +1,163 @@
+from .annotation import (
+    Classification,
+    Detection,
+    ObbDetection,
+    PoseDetection,
+    SegmentationDetection,
+    SemanticSegmentation,
+)
+from .common import (
+    FuzzyMatchingSet,
+    is_url,
+    is_valid_image,
+    parallel_process,
+    scale_bbox_xyxy,
+    url_to_image,
+)
+from .dataset_info import CocoConfig
+from .eval import (
+    average_precision,
+    bleu,
+    confusion,
+    edit_distance,
+    evaluate_detection,
+    evaluate_reid_market1501,
+    evaluate_reid_roc,
+    f1_score,
+    match_detections,
+    mean_average_precision,
+    pairwise_box_iou,
+    pck_accuracy,
+    rouge,
+    safe_divide,
+    topk_accuracy,
+)
+from .geo import (
+    circle_from_three_points,
+    fit_line,
+    intersect_lines,
+    is_point_in_polygon,
+    is_point_on_segment,
+    polygon_area,
+    rotate_points,
+    segment_intersection,
+)
+from .image_filter import ImageFilter
+from .io import (
+    list_files,
+    read_csv,
+    read_json,
+    read_pkl,
+    read_txt,
+    read_xml,
+    read_yaml,
+    read_yolo_txt,
+    save_csv,
+    save_json,
+    save_pkl,
+    save_txt,
+    save_xml,
+    save_yaml,
+    save_yolo_txt,
+)
+from .typing import (
+    Affine2D,
+    Circle,
+    KeyPoint,
+    Line,
+    Point2f,
+    PointGeometryMixin,
+    PointLike,
+    PointSet,
+    Polygon,
+    PolygonLike,
+    Rect,
+    Vector2,
+)
+from .visual import (
+    VideoReader,
+    draw_bbox,
+    draw_keypoints,
+    draw_masks,
+    generate_distinct_colors,
+    get_color,
+    imread,
+    imwrite,
+)
+
+__all__ = [
+    "Affine2D",
+    "Circle",
+    "Classification",
+    "CocoConfig",
+    "Detection",
+    "FuzzyMatchingSet",
+    "ImageFilter",
+    "KeyPoint",
+    "Line",
+    "ObbDetection",
+    "Point2f",
+    "PointGeometryMixin",
+    "PointLike",
+    "PointSet",
+    "Polygon",
+    "PolygonLike",
+    "PoseDetection",
+    "Rect",
+    "SegmentationDetection",
+    "SemanticSegmentation",
+    "Vector2",
+    "VideoReader",
+    "average_precision",
+    "bleu",
+    "circle_from_three_points",
+    "confusion",
+    "draw_bbox",
+    "draw_keypoints",
+    "draw_masks",
+    "edit_distance",
+    "evaluate_detection",
+    "evaluate_reid_market1501",
+    "evaluate_reid_roc",
+    "f1_score",
+    "fit_line",
+    "generate_distinct_colors",
+    "get_color",
+    "imread",
+    "imwrite",
+    "intersect_lines",
+    "is_point_in_polygon",
+    "is_point_on_segment",
+    "is_url",
+    "is_valid_image",
+    "list_files",
+    "match_detections",
+    "mean_average_precision",
+    "pairwise_box_iou",
+    "parallel_process",
+    "pck_accuracy",
+    "polygon_area",
+    "read_csv",
+    "read_json",
+    "read_pkl",
+    "read_txt",
+    "read_xml",
+    "read_yaml",
+    "read_yolo_txt",
+    "rotate_points",
+    "rouge",
+    "safe_divide",
+    "save_csv",
+    "save_json",
+    "save_pkl",
+    "save_txt",
+    "save_xml",
+    "save_yaml",
+    "save_yolo_txt",
+    "scale_bbox_xyxy",
+    "segment_intersection",
+    "topk_accuracy",
+    "url_to_image",
+]
+
+__version__ = "0.1.0"

kotoha/annotation.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+
+import numpy as np
+
+from kotoha.geo._types import KeyPoint, Polygon, Rect
+
+__all__ = [
+    "Classification",
+    "Detection",
+    "ObbDetection",
+    "PoseDetection",
+    "SegmentationDetection",
+    "SemanticSegmentation",
+]
+
+
+@dataclass(slots=True)
+class Classification:
+    """One ranked category prediction for an image."""
+
+    score: float
+    class_id: int
+    label: str | None = None
+
+    def to_numpy(self) -> np.ndarray:
+        return np.array([self.score, self.class_id], dtype=np.float32)
+
+    def to_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+@dataclass(slots=True)
+class SemanticSegmentation:
+    """Dense semantic class map for one image."""
+
+    mask: np.ndarray
+
+    def to_numpy(self) -> np.ndarray:
+        return self.mask
+
+    def to_dict(self) -> dict[str, object]:
+        return {"mask": self.mask.tolist()}
+
+
+@dataclass(slots=True)
+class Detection:
+    box: Rect
+    score: float
+    class_id: int
+    label: str | None = None
+
+    def to_numpy(self) -> np.ndarray:
+        return np.array(
+            [*self.box.to_list(), self.score, self.class_id],
+            dtype=np.float32,
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        data = asdict(self)
+        data["box"] = self.box.to_dict()
+        return data
+
+
+@dataclass(slots=True)
+class SegmentationDetection:
+    box: Rect
+    score: float
+    class_id: int
+    mask: np.ndarray
+    polygon: Polygon | None = None
+    label: str | None = None
+
+    def to_numpy(self) -> np.ndarray:
+        return np.array(
+            [*self.box.to_list(), self.score, self.class_id],
+            dtype=np.float32,
+        )
+
+    def to_dict(self) -> dict[str, object]:
+        data = asdict(self)
+        data["box"] = self.box.to_dict()
+        data["mask"] = self.mask.tolist()
+        if self.polygon is not None:
+            data["polygon"] = self.polygon.to_dict()
+        return data
+
+
+@dataclass(slots=True)
+class PoseDetection:
+    box: Rect
+    score: float
+    class_id: int
+    keypoints: list[KeyPoint]
+    label: str | None = None
+
+    def to_numpy(self) -> np.ndarray:
+        values: list[float] = [*self.box.to_list(), self.score, float(self.class_id)]
+        for keypoint in self.keypoints:
+            values.extend([keypoint.p.x, keypoint.p.y, keypoint.score or 0.0])
+        return np.array(values, dtype=np.float32)
+
+    def to_dict(self) -> dict[str, object]:
+        data = asdict(self)
+        data["keypoints"] = [keypoint.to_dict() for keypoint in self.keypoints]
+        data["box"] = self.box.to_dict()
+        return data
+
+
+@dataclass(slots=True)
+class ObbDetection:
+    quad: Polygon
+    score: float
+    class_id: int
+    label: str | None = None
+
+    def to_numpy(self) -> np.ndarray:
+        values = [coord for point in self.quad.vertices for coord in (point.x, point.y)]
+        values.extend([self.score, float(self.class_id)])
+        return np.array(values, dtype=np.float32)
+
+    def to_dict(self) -> dict[str, object]:
+        data = asdict(self)
+        data["quad"] = self.quad.to_dict()
+        return data

kotoha/common.py

@@ -0,0 +1,421 @@
+import logging
+import time
+from collections import Counter, defaultdict
+from collections.abc import Callable, Iterable, Sequence, Sized
+from multiprocessing import Pool as ProcessPool
+from multiprocessing.pool import ThreadPool
+from pathlib import Path
+from typing import Any, Literal, overload
+from urllib import parse, request
+
+import cv2
+import numpy as np
+import requests
+from PIL import Image
+from tqdm import tqdm
+
+from kotoha.eval import edit_distance
+
+logger = logging.getLogger(__name__)
+
+__all__ = [
+    "FuzzyMatchingSet",
+    "is_url",
+    "is_valid_image",
+    "parallel_process",
+    "scale_bbox_xyxy",
+    "url_to_image",
+]
+
+
+def is_url(url: str, check: bool = False) -> bool:
+    """
+    Validate if the given string is a URL and optionally check if the URL exists online.
+
+    Args:
+        url (str): The string to be validated as a URL.
+        check (bool, optional): If True, performs an additional check to see if the URL exists online.
+
+    Returns:
+        (bool): True for a valid URL. If 'check' is True, also returns True if the URL exists online.
+
+    Examples:
+        >>> valid = is_url("https://www.example.com")
+        >>> valid_and_exists = is_url("https://www.example.com", check=True)
+    """
+    try:
+        url = str(url)
+        result = parse.urlparse(url)
+        assert all([result.scheme, result.netloc])  # check if is url
+        if check:
+            with request.urlopen(url) as response:
+                return response.getcode() == 200  # check if exists online
+        return True
+    except Exception:
+        return False
+
+
+def url_to_image(url: str, readFlag: int = cv2.IMREAD_COLOR, headers=None) -> np.ndarray | None:
+    """
+    Download an image from a URL and decode it into an OpenCV image.
+
+    Args:
+        url (str): URL of the image to download.
+        readFlag (int, optional): Flag specifying the color type of a loaded image.
+            Defaults to cv2.IMREAD_COLOR.
+
+    Returns:
+        Optional[np.ndarray]: Decoded image as a numpy array if successful, else None.
+    """
+    if headers is None:
+        headers = {
+            "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36"
+        }
+    try:
+        response = requests.get(url, headers=headers, timeout=10)
+        response.raise_for_status()
+        image_array = np.frombuffer(response.content, dtype=np.uint8)
+        image = cv2.imdecode(image_array, readFlag)
+        return image
+    except Exception as e:
+        logger.warning("Failed to download or decode image from %s: %s", url, e)
+        return None
+
+
+def is_valid_image(path: str | Path) -> bool:
+    """
+    Checks whether the given file is a valid image by attempting to open and verify it.
+
+    Args:
+        path (str | Path): Path to the image file.
+
+    Returns:
+        bool: True if the image is valid, False otherwise.
+
+    Raises:
+        None: All exceptions are caught internally and False is returned.
+    """
+    try:
+        with Image.open(path) as img:
+            img.verify()  # Verify that it is, in fact, an image
+        return True
+    except Exception:
+        return False
+
+
+@overload
+def parallel_process[T](
+    func: Callable[[Any], T],
+    data: Iterable,
+    *,
+    use_threads: bool = False,
+    num_workers: int = 4,
+    store_results: Literal[True] = True,
+    show_progress: bool = True,
+    prog_desc: str | None = None,
+    prog_leave: bool = True,
+) -> tuple[list[T], float]: ...
+
+
+@overload
+def parallel_process[T](
+    func: Callable[[Any], T],
+    data: Iterable,
+    *,
+    use_threads: bool = False,
+    num_workers: int = 4,
+    store_results: Literal[False],
+    show_progress: bool = True,
+    prog_desc: str | None = None,
+    prog_leave: bool = True,
+) -> tuple[None, float]: ...
+
+
+def parallel_process[T](
+    func: Callable[[Any], T],
+    data: Iterable,
+    *,
+    use_threads: bool = False,
+    num_workers: int = 4,
+    store_results: bool = True,
+    show_progress: bool = True,
+    prog_desc: str | None = None,
+    prog_leave: bool = True,
+):
+    """
+    General-purpose function for parallel processing using multiple processes.
+
+    Args:
+        func (Callable):
+            The function to execute in parallel. It should accept a single input item
+            (each element of `data`) as its argument.
+
+        data (Iterable):
+            An iterable of input items, each passed as the argument to `func`.
+            Can be any iterable — e.g. list, generator, or range.
+
+        use_threads (bool, optional):
+            If True, use ThreadPool. Defaults to False (ProcessPool).
+
+        num_workers (int, optional):
+            Number of worker processes to use. Defaults to 4.
+
+        store_results (bool, optional):
+            Whether to collect and return the function outputs.
+            If False, results are discarded after execution (useful for side-effect-only tasks).
+            Defaults to True.
+
+        show_progress (bool): Whether to display a progress bar during processing.
+
+        prog_desc (str, optional):
+            Custom description text for the progress bar (from tqdm). Defaults to None.
+
+        prog_leave (bool, optional):
+            Whether to leave the progress bar on screen after completion. Defaults to True.
+
+    Returns:
+        Tuple[List[Any] | None, float]:
+            - results: List of all outputs from `func`, if `store_results=True`. Otherwise, None.
+            - duration: Total wall-clock execution time in seconds.
+
+    Raises:
+        TypeError:
+            If `func` is not callable.
+
+        Note:
+            Exceptions raised inside child processes are caught and logged internally.
+            The main process will not crash due to worker errors.
+    """
+
+    if not callable(func):
+        raise TypeError("func must be a callable function.")
+
+    start_time = time.time()
+
+    results = [] if store_results else None
+
+    PoolClass = ThreadPool if use_threads else ProcessPool
+
+    total_items = len(data) if isinstance(data, Sized) else None
+
+    with PoolClass(processes=num_workers) as pool:
+        iterator = pool.imap_unordered(func, data)
+        if show_progress:
+            iterator = tqdm(iterator, desc=prog_desc, leave=prog_leave, total=total_items)
+        for res in iterator:
+            if results is not None and res is not None:
+                results.append(res)
+
+    duration = time.time() - start_time
+
+    return (results, duration)
+
+
+class FuzzyMatchingSet:
+    """
+    Fuzzy string matcher based on n-gram inverted index and edit distance.
+
+    The matcher first uses n-gram features to collect a small set of candidate
+    words, then ranks those candidates by normalized edit distance.
+
+    Args:
+        words: Candidate words.
+        ngram_size: Feature width used for indexing. ``2`` is usually a good
+            default for short labels.
+        max_extra_length: Reject query words that are much longer than all
+            indexed words.
+        max_candidates: Maximum number of candidates to verify with edit distance.
+        case_sensitive: Whether matching should be case-sensitive.
+    """
+
+    def __init__(
+        self,
+        words: Iterable[str],
+        *,
+        ngram_size: int = 2,
+        max_extra_length: int = 2,
+        max_candidates: int = 50,
+        case_sensitive: bool = False,
+    ):
+        if ngram_size <= 0:
+            raise ValueError("ngram_size must be a positive integer")
+        if max_extra_length < 0:
+            raise ValueError("max_extra_length must be non-negative")
+        if max_candidates <= 0:
+            raise ValueError("max_candidates must be a positive integer")
+
+        self.ngram_size = ngram_size
+        self.max_extra_length = max_extra_length
+        self.max_candidates = max_candidates
+        self.case_sensitive = case_sensitive
+
+        self.words = list(dict.fromkeys(words))
+        self.normalized_words = [self._normalize(word) for word in self.words]
+
+        self.max_word_len = max((len(word) for word in self.normalized_words), default=0)
+
+        self.direct_indexes: dict[str, int] = {}
+        self.feature_indexes: dict[str, set[int]] = defaultdict(set)
+
+        for index, word in enumerate(self.normalized_words):
+            self.direct_indexes[word] = index
+
+            for feature in self._get_features(word):
+                self.feature_indexes[feature].add(index)
+
+    def match(self, word: str, threshold: float = 0.3) -> str | None:
+        """
+        Find the closest word in the set.
+
+        Args:
+            word: Query word.
+            threshold: Maximum normalized edit distance allowed. Smaller values
+                are stricter. For example, ``0.3`` means the edit distance must
+                be no more than 30% of the longer word length.
+
+        Returns:
+            The best matched original word, or ``None`` if no candidate is good enough.
+        """
+        result = self.match_with_score(word, threshold=threshold)
+        if result is None:
+            return None
+
+        matched_word, _ = result
+        return matched_word
+
+    def match_with_score(
+        self,
+        word: str,
+        threshold: float = 0.3,
+    ) -> tuple[str, float] | None:
+        """
+        Find the closest word and return its normalized distance.
+
+        Args:
+            word: Query word.
+            threshold: Maximum normalized edit distance allowed.
+
+        Returns:
+            ``(matched_word, score)`` if matched, otherwise ``None``.
+            The score is normalized edit distance, so smaller is better.
+        """
+        if threshold < 0:
+            raise ValueError("threshold must be non-negative")
+
+        if not self.words:
+            return None
+
+        query = self._normalize(word)
+
+        if len(query) > self.max_word_len + self.max_extra_length:
+            return None
+
+        direct_index = self.direct_indexes.get(query)
+        if direct_index is not None:
+            return self.words[direct_index], 0.0
+
+        candidates = self._get_candidates(query)
+        if not candidates:
+            return None
+
+        best_index: int | None = None
+        best_score: float | None = None
+
+        for index in candidates:
+            candidate = self.normalized_words[index]
+            score = edit_distance(query, candidate) / max(len(query), len(candidate), 1)
+
+            if best_score is None or score < best_score:
+                best_index = index
+                best_score = score
+
+        if best_index is None or best_score is None:
+            return None
+
+        if best_score <= threshold:
+            return self.words[best_index], best_score
+
+        return None
+
+    def _get_candidates(self, word: str) -> list[int]:
+        features = self._get_features(word)
+        counter: Counter[int] = Counter()
+
+        for feature in features:
+            for index in self.feature_indexes.get(feature, ()):
+                counter[index] += 1
+
+        return [index for index, _ in counter.most_common(self.max_candidates)]
+
+    def _normalize(self, word: str) -> str:
+        if self.case_sensitive:
+            return word
+        return word.lower()
+
+    def _get_features(self, word: str) -> tuple[str, ...]:
+        if not word:
+            return ("",)
+
+        if len(word) <= self.ngram_size:
+            return (word,)
+
+        return tuple(word[i : i + self.ngram_size] for i in range(len(word) - self.ngram_size + 1))
+
+
+def scale_bbox_xyxy(
+    xyxy: Sequence[float],
+    scale: float | tuple[float, float] = 1.0,
+    image_w: int | None = None,
+    image_h: int | None = None,
+    min_size: float = 1.0,
+) -> np.ndarray:
+    """
+    Scale (expand/shrink) a bbox centered at its midpoint and optionally clip to image bounds.
+
+    Args:
+        xyxy: [x1, y1, x2, y2]
+        scale: float or (sx, sy)
+            - float: uniform scaling
+            - tuple: separate x/y scaling
+        image_w: optional image width for clipping
+        image_h: optional image height for clipping
+        min_size: minimum width/height to avoid degenerate boxes
+
+    Returns:
+        np.ndarray: [x1, y1, x2, y2] float32
+    """
+    x1, y1, x2, y2 = map(float, xyxy)
+
+    # fix invalid box
+    if x2 < x1:
+        x1, x2 = x2, x1
+    if y2 < y1:
+        y1, y2 = y2, y1
+
+    sx, sy = (scale, scale) if isinstance(scale, (float, int)) else scale
+
+    cx = (x1 + x2) * 0.5
+    cy = (y1 + y2) * 0.5
+
+    bw = max((x2 - x1) * sx, min_size)
+    bh = max((y2 - y1) * sy, min_size)
+
+    nx1 = cx - bw * 0.5
+    ny1 = cy - bh * 0.5
+    nx2 = cx + bw * 0.5
+    ny2 = cy + bh * 0.5
+
+    # clip (careful: image boundary is usually [0, w-1])
+    if image_w is not None:
+        nx1 = np.clip(nx1, 0, image_w - 1)
+        nx2 = np.clip(nx2, 0, image_w - 1)
+
+    if image_h is not None:
+        ny1 = np.clip(ny1, 0, image_h - 1)
+        ny2 = np.clip(ny2, 0, image_h - 1)
+
+    # re-ensure ordering after clipping
+    x1, x2 = sorted((nx1, nx2))
+    y1, y2 = sorted((ny1, ny2))
+
+    return np.array([x1, y1, x2, y2], dtype=np.float32)