signlang-segmenter 0.1.0__tar.gz

signlang_segmenter-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohamed Yehia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

signlang_segmenter-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: signlang-segmenter
+Version: 0.1.0
+Summary: A Python library for sign language video and pose segmentation.
+Home-page: https://github.com/24-mohamedyehia/signlang-segmenter
+Author: Mohamed Yehia
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: opencv-python==4.11.0.86
+Requires-Dist: numpy==1.26.4
+Requires-Dist: matplotlib==3.7.3
+Requires-Dist: notebook==6.5.4
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# signlang-segmenter
+
+A Python library for sign language segmentation.
+
+## Optical Flow
+![motion curve with segments](./public/image.png)
+
+## Important Naming Note
+
+- Distribution/package name: `signlang-segmenter`
+- Python import name: `signlang_segmenter`
+
+Python imports use underscores, not dashes.
+
+## Current Layout
+
+```text
+signlang-segmenter/
+├── signlang_segmenter/
+│   ├── __init__.py
+│   ├── video/
+│   │   ├── __init__.py
+│   │   └── optical_flow/
+│   │       ├── __init__.py
+│   │       ├── segmenter.py
+│   │       ├── motion_analyzer.py
+│   │       ├── models.py
+│   │       ├── utils.py
+│   │       ├── exporter.py
+│   │       └── visualization.py
+│   └── pose/
+│       └── __init__.py
+├── examples/
+│   └── basic_pipeline.ipynb
+├── setup.py
+└── README.md
+```
+
+## Installation
+
+### Option 1: Install the library to use it
+
+If you only want to use the package in your own project, install it directly from GitHub:
+
+```bash
+python -m pip install "git+https://github.com/24-mohamedyehia/signlang-segmenter.git"
+```
+
+### Option 2: Install the project for development
+
+If you want to modify the code and contribute, use an isolated environment and editable install:
+
+1. Install Miniconda if needed.
+2. Run:
+
+```bash
+git clone https://github.com/24-mohamedyehia/signlang-segmenter.git
+cd signlang-segmenter
+conda create -n signlang-segmenter python=3.11 -y
+conda activate signlang-segmenter
+python -m pip install --upgrade pip
+python -m pip install -e .
+
+```
+
+## Quick Import Check
+
+```python
+import signlang_segmenter
+import signlang_segmenter.video
+import signlang_segmenter.pose
+```
+
+## Segmentation API (MVP)
+
+```python
+from signlang_segmenter.video import VideoSegmenter, SegmentExporter
+
+segmenter = VideoSegmenter(
+	roi_mode="full",
+	smooth_window=11,
+	min_len_sec=0.30,
+	merge_gap_sec=0.45,
+	pad_before_frames=10,
+	pad_after_frames=12,
+)
+
+segments, info = segmenter.segment(VIDEO_PATH)
+print(f"Found {len(segments)} segments: {segments}")
+
+exporter = SegmentExporter(out_dir="../output/segments_out")
+exporter.export(VIDEO_PATH, segments)
+```
+
+## Visualization
+
+```python
+from signlang_segmenter.video import plot_motion_segments
+
+plot_motion_segments(segments, info)
+```
+
+The plot includes:
+
+- motion raw curve
+- motion smooth curve
+- adaptive high/low thresholds
+- shaded spans for detected segments
+
+The `info` dict returned by `VideoSegmenter.segment` must include:
+
+- `motion_raw`
+- `motion_smooth`
+- `fps`
+- `frame_idx`
+- `th_high_arr`
+- `th_low_arr`

signlang_segmenter-0.1.0/README.md

@@ -0,0 +1,117 @@
+# signlang-segmenter
+
+A Python library for sign language segmentation.
+
+## Optical Flow
+![motion curve with segments](./public/image.png)
+
+## Important Naming Note
+
+- Distribution/package name: `signlang-segmenter`
+- Python import name: `signlang_segmenter`
+
+Python imports use underscores, not dashes.
+
+## Current Layout
+
+```text
+signlang-segmenter/
+├── signlang_segmenter/
+│   ├── __init__.py
+│   ├── video/
+│   │   ├── __init__.py
+│   │   └── optical_flow/
+│   │       ├── __init__.py
+│   │       ├── segmenter.py
+│   │       ├── motion_analyzer.py
+│   │       ├── models.py
+│   │       ├── utils.py
+│   │       ├── exporter.py
+│   │       └── visualization.py
+│   └── pose/
+│       └── __init__.py
+├── examples/
+│   └── basic_pipeline.ipynb
+├── setup.py
+└── README.md
+```
+
+## Installation
+
+### Option 1: Install the library to use it
+
+If you only want to use the package in your own project, install it directly from GitHub:
+
+```bash
+python -m pip install "git+https://github.com/24-mohamedyehia/signlang-segmenter.git"
+```
+
+### Option 2: Install the project for development
+
+If you want to modify the code and contribute, use an isolated environment and editable install:
+
+1. Install Miniconda if needed.
+2. Run:
+
+```bash
+git clone https://github.com/24-mohamedyehia/signlang-segmenter.git
+cd signlang-segmenter
+conda create -n signlang-segmenter python=3.11 -y
+conda activate signlang-segmenter
+python -m pip install --upgrade pip
+python -m pip install -e .
+
+```
+
+## Quick Import Check
+
+```python
+import signlang_segmenter
+import signlang_segmenter.video
+import signlang_segmenter.pose
+```
+
+## Segmentation API (MVP)
+
+```python
+from signlang_segmenter.video import VideoSegmenter, SegmentExporter
+
+segmenter = VideoSegmenter(
+	roi_mode="full",
+	smooth_window=11,
+	min_len_sec=0.30,
+	merge_gap_sec=0.45,
+	pad_before_frames=10,
+	pad_after_frames=12,
+)
+
+segments, info = segmenter.segment(VIDEO_PATH)
+print(f"Found {len(segments)} segments: {segments}")
+
+exporter = SegmentExporter(out_dir="../output/segments_out")
+exporter.export(VIDEO_PATH, segments)
+```
+
+## Visualization
+
+```python
+from signlang_segmenter.video import plot_motion_segments
+
+plot_motion_segments(segments, info)
+```
+
+The plot includes:
+
+- motion raw curve
+- motion smooth curve
+- adaptive high/low thresholds
+- shaded spans for detected segments
+
+The `info` dict returned by `VideoSegmenter.segment` must include:
+
+- `motion_raw`
+- `motion_smooth`
+- `fps`
+- `frame_idx`
+- `th_high_arr`
+- `th_low_arr`

signlang_segmenter-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

signlang_segmenter-0.1.0/setup.py

@@ -0,0 +1,25 @@
+from setuptools import find_packages, setup
+
+setup(
+    name="signlang-segmenter",
+    version="0.1.0",
+    description="A Python library for sign language video and pose segmentation.",
+    long_description=open("README.md", encoding="utf-8").read(),
+    long_description_content_type="text/markdown",
+    author="Mohamed Yehia",
+    url="https://github.com/24-mohamedyehia/signlang-segmenter",
+    packages=find_packages(),
+    python_requires=">=3.10",
+    install_requires=[
+        "opencv-python==4.11.0.86",
+        "numpy==1.26.4",
+        "matplotlib==3.7.3",
+        "notebook==6.5.4"
+    ],
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3 :: Only",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+    ],
+)

signlang_segmenter-0.1.0/signlang_segmenter/__init__.py

@@ -0,0 +1,4 @@
+"""Top-level package for signlang_segmenter."""
+
+__all__ = ["video", "pose"]
+__version__ = "0.1.0"

signlang_segmenter-0.1.0/signlang_segmenter/pose/__init__.py

@@ -0,0 +1 @@
+"""Pose segmentation subpackage placeholder."""

signlang_segmenter-0.1.0/signlang_segmenter/video/__init__.py

@@ -0,0 +1,17 @@
+"""Video segmentation package public API."""
+
+from .optical_flow import (
+    MotionAnalyzer,
+    Segment,
+    SegmentExporter,
+    VideoSegmenter,
+    plot_motion_segments,
+)
+
+__all__ = [
+    "Segment",
+    "MotionAnalyzer",
+    "VideoSegmenter",
+    "SegmentExporter",
+    "plot_motion_segments",
+]

signlang_segmenter-0.1.0/signlang_segmenter/video/optical_flow/__init__.py

@@ -0,0 +1,15 @@
+"""Optical-flow segmentation algorithm package."""
+
+from .exporter import SegmentExporter
+from .models import Segment
+from .motion_analyzer import MotionAnalyzer
+from .segmenter import VideoSegmenter
+from .visualization import plot_motion_segments
+
+__all__ = [
+    "Segment",
+    "MotionAnalyzer",
+    "VideoSegmenter",
+    "SegmentExporter",
+    "plot_motion_segments",
+]

signlang_segmenter-0.1.0/signlang_segmenter/video/optical_flow/exporter.py

@@ -0,0 +1,111 @@
+"""SegmentExporter writes detected segments as individual video clips."""
+
+import os
+import shutil
+import subprocess
+
+import cv2
+
+from .models import Segment
+
+
+class SegmentExporter:
+    """Export Segment objects as per-segment MP4 clip files."""
+
+    _H264_CODECS = ("avc1", "H264", "X264")
+    _WRITER_ATTEMPT_ORDER = ("mp4v", "avc1", "H264", "X264")
+
+    def __init__(self, out_dir: str = "segments_out") -> None:
+        self.out_dir = out_dir
+
+    def export(self, video_path: str, segments: list[Segment]) -> str:
+        """Cut and export segments from a source video to out_dir."""
+        os.makedirs(self.out_dir, exist_ok=True)
+
+        cap = cv2.VideoCapture(video_path)
+        if not cap.isOpened():
+            raise FileNotFoundError(f"Cannot open video: {video_path}")
+
+        fps = cap.get(cv2.CAP_PROP_FPS)
+        if fps <= 0:
+            fps = 25.0
+        w = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+        h = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+
+        for i, seg in enumerate(segments, start=1):
+            self._write_segment(cap, seg, i, fps, (w, h))
+
+        cap.release()
+        return self.out_dir
+
+    def _write_segment(
+        self,
+        cap: cv2.VideoCapture,
+        seg: Segment,
+        index: int,
+        fps: float,
+        size: tuple[int, int],
+    ) -> None:
+        final_path = os.path.join(
+            self.out_dir,
+            f"seg_{index:03d}_{seg.start_frame}_{seg.end_frame}.mp4",
+        )
+        raw_path = final_path.replace(".mp4", "_raw.mp4")
+
+        writer, codec_used = self._open_writer(raw_path, fps, size)
+
+        cap.set(cv2.CAP_PROP_POS_FRAMES, seg.start_frame)
+        for _ in range(seg.start_frame, seg.end_frame + 1):
+            ret, frame = cap.read()
+            if not ret:
+                break
+            writer.write(frame)
+        writer.release()
+
+        if codec_used.lower() in {c.lower() for c in self._H264_CODECS}:
+            os.replace(raw_path, final_path)
+            return
+
+        if self._transcode_to_h264(raw_path, final_path):
+            if os.path.exists(raw_path):
+                os.remove(raw_path)
+        else:
+            os.replace(raw_path, final_path)
+
+    def _open_writer(
+        self,
+        path: str,
+        fps: float,
+        size: tuple[int, int],
+    ) -> tuple[cv2.VideoWriter, str]:
+        for codec in self._WRITER_ATTEMPT_ORDER:
+            writer = cv2.VideoWriter(path, cv2.VideoWriter_fourcc(*codec), fps, size)
+            if writer.isOpened():
+                return writer, codec
+            writer.release()
+        raise RuntimeError("Could not initialize VideoWriter with available codecs.")
+
+    @staticmethod
+    def _transcode_to_h264(src_path: str, dst_path: str) -> bool:
+        ffmpeg = shutil.which("ffmpeg")
+        if ffmpeg is None:
+            return False
+        cmd = [
+            ffmpeg,
+            "-y",
+            "-loglevel",
+            "error",
+            "-i",
+            src_path,
+            "-vf",
+            "scale=trunc(iw/2)*2:trunc(ih/2)*2",
+            "-c:v",
+            "libx264",
+            "-pix_fmt",
+            "yuv420p",
+            "-movflags",
+            "+faststart",
+            "-an",
+            dst_path,
+        ]
+        return subprocess.run(cmd).returncode == 0

signlang_segmenter-0.1.0/signlang_segmenter/video/optical_flow/models.py

@@ -0,0 +1,24 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class Segment:
+    """Represents a single motion segment identified in a video."""
+
+    start_frame: int
+    end_frame: int
+    video_path: str = ""
+
+    @property
+    def length_frames(self) -> int:
+        return self.end_frame - self.start_frame + 1
+
+    def to_seconds(self, fps: float) -> tuple[float, float]:
+        """Return (start_sec, end_sec) for this segment."""
+        return self.start_frame / fps, self.end_frame / fps
+
+    def __repr__(self) -> str:
+        return (
+            f"Segment(start={self.start_frame}, end={self.end_frame}, "
+            f"len={self.length_frames})"
+        )

signlang_segmenter-0.1.0/signlang_segmenter/video/optical_flow/motion_analyzer.py

@@ -0,0 +1,87 @@
+"""MotionAnalyzer computes a per-frame motion-energy curve via optical flow."""
+
+import cv2
+import numpy as np
+
+
+class MotionAnalyzer:
+    """Extract a 1-D motion-energy signal from a video using Farneback flow."""
+
+    def __init__(
+        self,
+        roi_mode: str = "upper",
+        resize_width: int = 320,
+        step: int = 1,
+    ) -> None:
+        if roi_mode not in ("full", "upper"):
+            raise ValueError("roi_mode must be 'full' or 'upper'")
+        self.roi_mode = roi_mode
+        self.resize_width = resize_width
+        self.step = max(1, int(step))
+
+    def compute(self, video_path: str) -> tuple[np.ndarray, np.ndarray, float, int]:
+        """Compute motion-energy for a video path."""
+        cap = cv2.VideoCapture(video_path)
+        if not cap.isOpened():
+            raise FileNotFoundError(f"Cannot open video: {video_path}")
+
+        fps = cap.get(cv2.CAP_PROP_FPS)
+        if fps <= 0:
+            fps = 25.0
+        total_frames = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+
+        ret, frame = cap.read()
+        if not ret:
+            cap.release()
+            raise RuntimeError("Failed to read the first frame.")
+
+        h0, w0 = frame.shape[:2]
+        scale = 1.0
+        if self.resize_width is not None and w0 > self.resize_width:
+            scale = self.resize_width / w0
+            frame = cv2.resize(frame, (int(w0 * scale), int(h0 * scale)))
+        h, w = frame.shape[:2]
+
+        prev_gray = cv2.cvtColor(self._crop_roi(frame, h), cv2.COLOR_BGR2GRAY)
+        motion: list[float] = []
+        frame_idx: list[int] = [0]
+        idx = 0
+
+        while True:
+            for _ in range(self.step):
+                ret, frame = cap.read()
+                idx += 1
+                if not ret:
+                    cap.release()
+                    return (
+                        np.array(motion, dtype=np.float32),
+                        np.array(frame_idx, dtype=int),
+                        fps,
+                        total_frames,
+                    )
+
+            if scale != 1.0:
+                frame = cv2.resize(frame, (w, h))
+
+            gray = cv2.cvtColor(self._crop_roi(frame, h), cv2.COLOR_BGR2GRAY)
+            flow = cv2.calcOpticalFlowFarneback(
+                prev_gray,
+                gray,
+                None,
+                pyr_scale=0.5,
+                levels=3,
+                winsize=15,
+                iterations=3,
+                poly_n=5,
+                poly_sigma=1.2,
+                flags=0,
+            )
+            mag, _ = cv2.cartToPolar(flow[..., 0], flow[..., 1])
+            motion.append(float(np.mean(mag)))
+            frame_idx.append(idx)
+            prev_gray = gray
+
+    def _crop_roi(self, frame: np.ndarray, h: int) -> np.ndarray:
+        if self.roi_mode == "full":
+            return frame
+        return frame[: int(h * 0.7), :]

signlang_segmenter-0.1.0/signlang_segmenter/video/optical_flow/segmenter.py

@@ -0,0 +1,122 @@
+"""VideoSegmenter detects and returns motion-based segments in a video."""
+
+import numpy as np
+
+from .models import Segment
+from .motion_analyzer import MotionAnalyzer
+from .utils import (
+    fill_short_gaps,
+    hysteresis_binarize_var,
+    mask_to_segments,
+    moving_average,
+    postprocess_segments,
+)
+
+
+class VideoSegmenter:
+    """High-level optical-flow segmentation pipeline."""
+
+    def __init__(
+        self,
+        roi_mode: str = "upper",
+        resize_width: int = 320,
+        step: int = 1,
+        smooth_window: int = 7,
+        min_len_sec: float = 0.25,
+        merge_gap_sec: float = 0.15,
+        pad_before_frames: int = 0,
+        pad_after_frames: int = 0,
+    ) -> None:
+        self.smooth_window = smooth_window
+        self.min_len_sec = min_len_sec
+        self.merge_gap_sec = merge_gap_sec
+        self.pad_before_frames = max(0, int(pad_before_frames))
+        self.pad_after_frames = max(0, int(pad_after_frames))
+        self._analyzer = MotionAnalyzer(
+            roi_mode=roi_mode,
+            resize_width=resize_width,
+            step=step,
+        )
+
+    def segment(self, video_path: str) -> tuple[list[Segment], dict]:
+        """Run segmentation on video_path and return segments with diagnostics."""
+        motion, frame_idx, fps, total_frames = self._analyzer.compute(video_path)
+        motion = motion.astype(np.float32)
+        motion_s = moving_average(motion, self.smooth_window)
+
+        th_high_arr, th_low_arr = self._adaptive_thresholds(motion_s, fps)
+        active = hysteresis_binarize_var(motion_s, th_high_arr, th_low_arr)
+
+        kernel = np.ones(max(1, int(fps * 0.25)))
+        active = np.convolve(active.astype(float), kernel, mode="same") > 0
+
+        active = fill_short_gaps(active, max_gap_frames=max(1, int(fps * 0.6)))
+        segs = mask_to_segments(active)
+
+        real_segments = self._remap_to_frames(segs, frame_idx)
+
+        min_len_frames = max(1, int(self.min_len_sec * fps))
+        merge_gap_frames = max(0, int(self.merge_gap_sec * fps))
+        real_segments = postprocess_segments(
+            real_segments,
+            min_len_frames=min_len_frames,
+            merge_gap_frames=merge_gap_frames,
+        )
+        real_segments = self._pad_segments(real_segments, total_frames)
+
+        for seg in real_segments:
+            seg.video_path = video_path
+
+        info = {
+            "fps": fps,
+            "total_frames": total_frames,
+            "th_high_arr": th_high_arr,
+            "th_low_arr": th_low_arr,
+            "motion_raw": motion,
+            "motion_smooth": motion_s,
+            "frame_idx": frame_idx,
+            "active_mask": active,
+        }
+        return real_segments, info
+
+    @staticmethod
+    def _adaptive_thresholds(
+        motion_s: np.ndarray,
+        fps: float,
+    ) -> tuple[np.ndarray, np.ndarray]:
+        """Compute local adaptive high and low thresholds."""
+        win = max(5, int(fps * 1.0))
+        local_mean = moving_average(motion_s, win)
+        local_var = moving_average((motion_s - local_mean) ** 2, win)
+        local_std = np.sqrt(np.maximum(local_var, 1e-8))
+        th_high = local_mean + 1.15 * local_std
+        th_low = local_mean + 0.65 * local_std
+        return th_high, th_low
+
+    @staticmethod
+    def _remap_to_frames(segs: list[Segment], frame_idx: np.ndarray) -> list[Segment]:
+        """Map motion-array segment indices back to original frame indices."""
+        real_segments: list[Segment] = []
+        for seg in segs:
+            start = int(frame_idx[seg.start_frame + 1])
+            end = int(frame_idx[seg.end_frame + 1])
+            real_segments.append(Segment(start, end))
+        return real_segments
+
+    def _pad_segments(self, segments: list[Segment], total_frames: int) -> list[Segment]:
+        """Expand segment boundaries by configured context then merge overlaps."""
+        if not segments:
+            return []
+
+        if self.pad_before_frames == 0 and self.pad_after_frames == 0:
+            return segments
+
+        max_end = max(0, int(total_frames) - 1)
+        expanded = [
+            Segment(
+                max(0, seg.start_frame - self.pad_before_frames),
+                min(max_end, seg.end_frame + self.pad_after_frames),
+            )
+            for seg in segments
+        ]
+        return postprocess_segments(expanded, min_len_frames=1, merge_gap_frames=0)

signlang_segmenter-0.1.0/signlang_segmenter/video/optical_flow/utils.py

@@ -0,0 +1,99 @@
+"""Signal-processing utilities used by the optical-flow segmentation pipeline."""
+
+import numpy as np
+
+from .models import Segment
+
+
+def moving_average(x: np.ndarray, window: int) -> np.ndarray:
+    """Smooth a 1-D array with a uniform moving average."""
+    if window <= 1:
+        return x.astype(np.float32)
+    kernel = np.ones(int(window), dtype=np.float32) / int(window)
+    return np.convolve(x, kernel, mode="same")
+
+
+def hysteresis_binarize_var(
+    signal: np.ndarray,
+    th_high_arr: np.ndarray,
+    th_low_arr: np.ndarray,
+) -> np.ndarray:
+    """Hysteresis thresholding with per-sample adaptive thresholds."""
+    active = np.zeros_like(signal, dtype=bool)
+    on = False
+    for i, value in enumerate(signal):
+        if not on and value >= th_high_arr[i]:
+            on = True
+        elif on and value <= th_low_arr[i]:
+            on = False
+        active[i] = on
+    return active
+
+
+def fill_short_gaps(active: np.ndarray, max_gap_frames: int) -> np.ndarray:
+    """Fill short OFF gaps between two ON regions in a boolean mask."""
+    mask = active.copy().astype(bool)
+    n = len(mask)
+    i = 0
+    while i < n:
+        if mask[i]:
+            i += 1
+            continue
+
+        j = i
+        while j < n and not mask[j]:
+            j += 1
+
+        gap_len = j - i
+        left_true = i - 1 >= 0 and mask[i - 1]
+        right_true = j < n and mask[j]
+        if left_true and right_true and gap_len <= max_gap_frames:
+            mask[i:j] = True
+        i = j
+
+    return mask
+
+
+def mask_to_segments(active: np.ndarray) -> list[Segment]:
+    """Convert a boolean activity mask to a list of Segment objects."""
+    segments: list[Segment] = []
+    in_segment = False
+    start = 0
+
+    for i, is_active in enumerate(active):
+        if is_active and not in_segment:
+            in_segment = True
+            start = i
+        elif (not is_active) and in_segment:
+            in_segment = False
+            segments.append(Segment(start, i - 1))
+
+    if in_segment:
+        segments.append(Segment(start, len(active) - 1))
+
+    return segments
+
+
+def postprocess_segments(
+    segments: list[Segment],
+    min_len_frames: int,
+    merge_gap_frames: int,
+) -> list[Segment]:
+    """Drop short segments and merge close neighboring segments."""
+    if not segments:
+        return []
+
+    filtered = [s for s in segments if s.length_frames >= min_len_frames]
+    if not filtered:
+        return []
+
+    merged = [filtered[0]]
+    for seg in filtered[1:]:
+        prev = merged[-1]
+        gap = seg.start_frame - prev.end_frame - 1
+        if gap <= merge_gap_frames:
+            merged[-1] = Segment(prev.start_frame, max(prev.end_frame, seg.end_frame))
+        else:
+            merged.append(seg)
+
+    return merged

signlang_segmenter-0.1.0/signlang_segmenter/video/optical_flow/visualization.py

@@ -0,0 +1,67 @@
+"""Visualization helpers for motion-based segmentation outputs."""
+
+from collections.abc import Iterable
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+from .models import Segment
+
+
+def plot_motion_segments(
+    segments: Iterable[Segment],
+    info: dict,
+    *,
+    figsize: tuple[float, float] = (14.0, 4.0),
+    segment_alpha: float = 0.2,
+    title: str = "Motion-based segmentation (shaded = detected segments)",
+    show: bool = True,
+):
+    """Plot motion curves, thresholds, and shaded detected segments.
+
+    Expected keys in info: motion_raw, motion_smooth, fps, frame_idx, th_high_arr, th_low_arr.
+    """
+    required = {
+        "motion_raw",
+        "motion_smooth",
+        "fps",
+        "frame_idx",
+        "th_high_arr",
+        "th_low_arr",
+    }
+    missing = [k for k in required if k not in info]
+    if missing:
+        raise KeyError(f"Missing required info keys: {missing}")
+
+    motion = np.asarray(info["motion_raw"])
+    motion_s = np.asarray(info["motion_smooth"])
+    th_high_arr = np.asarray(info["th_high_arr"])
+    th_low_arr = np.asarray(info["th_low_arr"])
+    fps = float(info["fps"])
+    frame_idx = np.asarray(info["frame_idx"])
+
+    if fps <= 0:
+        raise ValueError("fps must be > 0")
+    if frame_idx.size < 2:
+        raise ValueError("frame_idx must contain at least two indices")
+
+    t = frame_idx[1:] / fps
+
+    fig, ax = plt.subplots(figsize=figsize)
+    ax.plot(t, motion, label="motion raw")
+    ax.plot(t, motion_s, label="motion smooth")
+    ax.plot(t, th_high_arr, linestyle="--", label="th_high")
+    ax.plot(t, th_low_arr, linestyle="--", label="th_low")
+
+    for seg in segments:
+        ax.axvspan(seg.start_frame / fps, seg.end_frame / fps, alpha=segment_alpha)
+
+    ax.set_xlabel("Time (sec)")
+    ax.set_ylabel("Motion energy")
+    ax.legend()
+    ax.set_title(title)
+
+    if show:
+        plt.show()
+
+    return fig, ax

signlang_segmenter-0.1.0/signlang_segmenter.egg-info/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: signlang-segmenter
+Version: 0.1.0
+Summary: A Python library for sign language video and pose segmentation.
+Home-page: https://github.com/24-mohamedyehia/signlang-segmenter
+Author: Mohamed Yehia
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: opencv-python==4.11.0.86
+Requires-Dist: numpy==1.26.4
+Requires-Dist: matplotlib==3.7.3
+Requires-Dist: notebook==6.5.4
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# signlang-segmenter
+
+A Python library for sign language segmentation.
+
+## Optical Flow
+![motion curve with segments](./public/image.png)
+
+## Important Naming Note
+
+- Distribution/package name: `signlang-segmenter`
+- Python import name: `signlang_segmenter`
+
+Python imports use underscores, not dashes.
+
+## Current Layout
+
+```text
+signlang-segmenter/
+├── signlang_segmenter/
+│   ├── __init__.py
+│   ├── video/
+│   │   ├── __init__.py
+│   │   └── optical_flow/
+│   │       ├── __init__.py
+│   │       ├── segmenter.py
+│   │       ├── motion_analyzer.py
+│   │       ├── models.py
+│   │       ├── utils.py
+│   │       ├── exporter.py
+│   │       └── visualization.py
+│   └── pose/
+│       └── __init__.py
+├── examples/
+│   └── basic_pipeline.ipynb
+├── setup.py
+└── README.md
+```
+
+## Installation
+
+### Option 1: Install the library to use it
+
+If you only want to use the package in your own project, install it directly from GitHub:
+
+```bash
+python -m pip install "git+https://github.com/24-mohamedyehia/signlang-segmenter.git"
+```
+
+### Option 2: Install the project for development
+
+If you want to modify the code and contribute, use an isolated environment and editable install:
+
+1. Install Miniconda if needed.
+2. Run:
+
+```bash
+git clone https://github.com/24-mohamedyehia/signlang-segmenter.git
+cd signlang-segmenter
+conda create -n signlang-segmenter python=3.11 -y
+conda activate signlang-segmenter
+python -m pip install --upgrade pip
+python -m pip install -e .
+
+```
+
+## Quick Import Check
+
+```python
+import signlang_segmenter
+import signlang_segmenter.video
+import signlang_segmenter.pose
+```
+
+## Segmentation API (MVP)
+
+```python
+from signlang_segmenter.video import VideoSegmenter, SegmentExporter
+
+segmenter = VideoSegmenter(
+	roi_mode="full",
+	smooth_window=11,
+	min_len_sec=0.30,
+	merge_gap_sec=0.45,
+	pad_before_frames=10,
+	pad_after_frames=12,
+)
+
+segments, info = segmenter.segment(VIDEO_PATH)
+print(f"Found {len(segments)} segments: {segments}")
+
+exporter = SegmentExporter(out_dir="../output/segments_out")
+exporter.export(VIDEO_PATH, segments)
+```
+
+## Visualization
+
+```python
+from signlang_segmenter.video import plot_motion_segments
+
+plot_motion_segments(segments, info)
+```
+
+The plot includes:
+
+- motion raw curve
+- motion smooth curve
+- adaptive high/low thresholds
+- shaded spans for detected segments
+
+The `info` dict returned by `VideoSegmenter.segment` must include:
+
+- `motion_raw`
+- `motion_smooth`
+- `fps`
+- `frame_idx`
+- `th_high_arr`
+- `th_low_arr`

signlang_segmenter-0.1.0/signlang_segmenter.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+LICENSE
+README.md
+setup.py
+signlang_segmenter/__init__.py
+signlang_segmenter.egg-info/PKG-INFO
+signlang_segmenter.egg-info/SOURCES.txt
+signlang_segmenter.egg-info/dependency_links.txt
+signlang_segmenter.egg-info/requires.txt
+signlang_segmenter.egg-info/top_level.txt
+signlang_segmenter/pose/__init__.py
+signlang_segmenter/video/__init__.py
+signlang_segmenter/video/optical_flow/__init__.py
+signlang_segmenter/video/optical_flow/exporter.py
+signlang_segmenter/video/optical_flow/models.py
+signlang_segmenter/video/optical_flow/motion_analyzer.py
+signlang_segmenter/video/optical_flow/segmenter.py
+signlang_segmenter/video/optical_flow/utils.py
+signlang_segmenter/video/optical_flow/visualization.py

signlang_segmenter-0.1.0/signlang_segmenter.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

signlang_segmenter-0.1.0/signlang_segmenter.egg-info/requires.txt

@@ -0,0 +1,4 @@
+opencv-python==4.11.0.86
+numpy==1.26.4
+matplotlib==3.7.3
+notebook==6.5.4

signlang_segmenter-0.1.0/signlang_segmenter.egg-info/top_level.txt

@@ -0,0 +1 @@
+signlang_segmenter