MotionShot README

项目的 README,来自 github.com/AhmadHassan-BTed/MotionShot。合并为一个 markdown 文件:README.md。

MotionShot Banner

MotionShot

High-Performance Stroboscopic Action Sequence Camera for Android

Status Platform Language UI License

Engineered and maintained by Ahmad Hassan (B-Ted)


Overview & Vision

Human movement is inherently transient. Whether an athlete sprinting, a dancer executing a spin, a gymnast mid-air, or a child jumping, fleeting physical motion unfolds and vanishes within fractions of a second.

MotionShot bridges high-speed mobile computer vision with human kinetic expression. Inspired by Sony's legacy Motion Shot technology, MotionShot captures dynamic action bursts and synthesizes a single, multi-pose stroboscopic composite image directly on-device in real time.

Operating entirely offline with zero cloud latency and zero reliance on heavy AI neural networks, MotionShot renders motion as an aligned visual trajectory: sharp, stabilized, and captured in full sensor resolution.


Visual Showcase

Camera Viewfinder Hardware Sliders Step 1 Raw Gallery Composite Result
Viewfinder Sliders Raw Gallery Composite Result

Technical Specifications

Parameter Specification & Range Engineering Function
Timer Window 1s, 2s, 5s, Custom (1–60s) Dynamic sequence capture deadline
Frame Count 5, 15, 25, Custom (2–50) Trajectory density sampling points
Shutter Speed Auto, 1/30s to 1/8000s Logarithmic hardware motion-freeze slider
ISO Sensitivity Auto, ISO 50 to ISO 102,400 Continuous sensor gain boost
Stabilization $\pm 16\text{px}$ 2D translation search Sub-5ms background micro-jitter alignment
Blending Engine PorterDuff.Mode.SRC_OVER Sequential alpha layer compositing
Persistence SharedPreferences Automatic parameter restoration across sessions

Key Features


Architecture Overview

MotionShot follows a strict Contract-Based Clean Architecture, decoupling UI presentation, state orchestration, image processing algorithms, and Camera2 hardware controls.

graph TD
    subgraph Presentation["Presentation Layer (Jetpack Compose)"]
        MA[MainActivity] --> CS[CameraScreen]
        CS --> CP[CameraPreview Viewfinder]
        CS --> CC[CaptureControls Sheet & Sliders]
        CS --> RV[Step1ResultView Flipbook Gallery]
    end

    subgraph Domain["Domain Contracts & Storage"]
        VM[MotionShotViewModel] --> |Preferences| PR[PreferencesRepository]
        VM --> |Pluggable Contract| ME[MotionEngine Interface]
    end

    subgraph Engine["Image Processing Realizations"]
        ME --> FDEM[FastDifferenceMotionEngine]
        FDEM --> STAB[ImageStabilizer Engine]
        FDEM --> DIFF[FrameDifferencer Engine]
        FDEM --> MORPH[MorphologyOps Engine]
        FDEM --> CCMP[CanvasCompositor Engine]
    end

    subgraph Hardware["Hardware Capture Layer (CameraX / Camera2)"]
        VM --> FA[FrameAnalyzer]
        FA --> YR[Native C++ YuvToRgb]
        VM --> C2[Camera2Interop Control]
        C2 --> CP
    end

Technical Processing Pipeline

Each captured frame sequence moves through a zero-allocation processing pipeline:

flowchart TD
    A["Raw Frame Burst (N Frames)"] --> B["1. 2D Translation Alignment (ImageStabilizer)"]
    B --> C["2. Normalized Chromaticity Differencing (FrameDifferencer)"]
    C --> D["3. 3x3 Morphological Opening (MorphologyOps)"]
    D --> E["4. Soft Contour Edge Feathering"]
    E --> F["5. Sequence Alpha Decay (CanvasCompositor)"]
    F --> G["Final Stroboscopic Composite Image"]

Request Lifecycle & Frame Acquisition

sequenceDiagram
    autonumber
    actor User
    participant UI as CameraScreen / Controls
    participant VM as MotionShotViewModel
    participant Analyzer as FrameAnalyzer
    participant Engine as MotionEngine

    User->>UI: Tap Capture Button
    UI->>VM: onCaptureToggle()
    VM->>VM: Lock Start Time & Set Hard Deadline (T seconds)
    
    loop Dynamic Time Window (T / N-1)
        VM->>Analyzer: shouldCapture.set(true)
        Analyzer-->>VM: frameChannel.receive() [Time-Bounded Timeout Guard]
    end

    VM->>Engine: process(capturedFrames)
    Engine->>Engine: 2D Translation Alignment
    Engine->>Engine: Normalized Chromaticity Masking
    Engine->>Engine: 3x3 Morphological Noise Removal
    Engine->>Engine: Native Canvas PorterDuff Stamping
    Engine-->>VM: Return Composite Bitmap
    VM->>UI: Phase = Done (Show Result & Interactive Flipbook)

Technical Deep-Dives

1. Handheld 2D Translation Alignment Mathematics

Camera micro-jitter causes static background edges to shift between frames. MotionShot computes an optimal $(\Delta x, \Delta y)$ alignment vector over a $\pm 16\text{px}$ search window using a 4x grid subsampling strategy:

$$\Delta x, \Delta y = \arg\min_{dx, dy} \sum_{y, x} \left| \text{Base}(x, y) - \text{Curr}(x + dx, y + dy) \right|$$

Target frame pixels are shifted by $(\Delta x, \Delta y)$ prior to motion differencing, locking static background elements 100% in place.

2. Normalized Chromaticity Color Space (r, g)

Camera auto-exposure shifts brightness across frames. Simple RGB subtraction fails under exposure drift. MotionShot converts pixels to Normalized Chromaticity:

$$r = \frac{R}{R + G + B + 1}, \quad g = \frac{G}{R + G + B + 1}$$

Combining chromaticity distance $\Delta_{\text{chroma}} = |r_1 - r_0| + |g_1 - g_0|$ with BT.601 luminance separation ($\Delta_Y = |Y_1 - Y_0|$) ensures lighting fluctuations and shadows are 100% ignored.

3. Camera2 Hardware Exposure & ISO Interop

High shutter speeds (1/500s to 1/8000s) eliminate subject motion blur. CameraX parameters are applied directly to the Camera2 HAL via Camera2CameraControl:

  • CaptureRequest.CONTROL_AE_MODE: Set to OFF for manual exposure control.
  • CaptureRequest.SENSOR_EXPOSURE_TIME: Configured in nanoseconds via logarithmic slider.
  • CaptureRequest.SENSOR_SENSITIVITY: Configured up to ISO 102,400 for low-light gain compensation.

Repository Structure

bted.app.motionshot/
├── capture/
│   ├── FrameAnalyzer.kt       # CameraX ImageAnalysis analyzer
│   └── YuvToRgb.kt            # Native C++ accelerated ImageProxy to Bitmap
├── data/
│   └── PreferencesRepository.kt # SharedPreferences persistence (Timer, Count, Shutter, ISO)
├── engine/
│   ├── MotionEngine.kt        # Pluggable engine interface contract
│   ├── FastDifferenceMotionEngine.kt  # Math & Differencing engine
│   ├── MotionEngineFactory.kt # Engine registry & factory
│   └── DebugPipelineConfig.kt # Step-by-step pipeline config
├── processing/
│   ├── FrameDifferencer.kt    # Normalized chromaticity & luminance differencer
│   ├── ImageStabilizer.kt     # Pixel-to-pixel 2D handheld stabilizer
│   ├── MorphologyOps.kt       # 3x3 Erode, Dilate, and Morphological Opening
│   └── CanvasCompositor.kt    # Native Canvas PorterDuff compositing
├── ui/
│   ├── components/
│   │   ├── CaptureControls.kt # Sliders, custom input, tap-to-record button
│   │   └── LoadingOverlay.kt  # Pulsing progress overlay
│   ├── state/
│   │   ├── MotionShotUiState.kt # UI state holder & CameraParameterUtils
│   │   └── CapturePhase.kt    # Capture phase lifecycle
│   ├── theme/                 # Dark aesthetic color, typography, theme
│   ├── CameraPreview.kt       # CameraX preview + Camera2Interop hardware controls
│   └── CameraScreen.kt        # Root camera & result flipbook gallery screen
└── viewmodel/
    └── MotionShotViewModel.kt # StateFlow, preferences, capture loop, engine dispatcher

Building & Requirements

System Requirements

Local Build Commands

# Clone the repository
git clone https://github.com/AhmadHassan-BTed/MotionShot.git
cd MotionShot

# Execute unit tests
./gradlew test

# Build Debug APK
./gradlew assembleDebug

Engineered and maintained by Ahmad Hassan (B-Ted)

MotionShot (AhmadHassan-BTed/MotionShot)

正在搜索数据库…

这是什么?MotionShot 是一款 Android 相机应用,它会拍摄一段快速运动的连续画面,并将这些帧合并成一张频闪照片,在同一张照片中展示主体在多个时间点的位置。整个过程依靠设备端的计算机视觉完成。
这是一个独立的相机应用,还是我可以添加到自己项目中的库?它是一个独立的原生 Android 应用,使用 Kotlin、Jetpack Compose 和 CameraX 开发,不是库,也不是插件。
我该如何构建和运行 MotionShot?克隆仓库,并用 Android Studio Ladybug/Jellyfish 或更新版本打开,然后使用 Gradle 8.13+,以 Compile SDK 37 进行构建。
它需要什么版本的 Android 和什么硬件?它需要 Android API 24(Min SDK 24)或更高版本,并且设备要支持 Camera2 HAL。手动快门速度和 ISO 控制是直接通过 Camera2CameraControl 应用的,因此这一点是必需的。
防抖功能能修正各种相机抖动吗?防抖只能修正手持时产生的细微抖动,方法是在静态背景边缘附近的有限像素范围内进行搜索。它并不是用来补偿相机的大幅主动移动的。
它会把我的照片发送到别处吗?不会。所有处理都在设备本地完成,不会上传到云端,也不依赖庞大的神经网络。
它如何区分运动的主体与曝光或阴影的变化?在比较帧之前,它会先把像素转换为归一化的 r、g 色度,以及 BT.601 亮度。这样,自动曝光的变化和阴影就不会被误判为运动。
我能控制拍摄的时机和帧数吗?可以。拍摄前可以调整定时窗口(1 秒、2 秒、5 秒,或自定义的 1–60 秒范围)以及帧数(5、15、25,或自定义的 2–50 帧)。
为什么它采用可插拔的 MotionEngine 架构?MotionEngine 接口和 MotionEngineFactory 将运动处理算法与界面解耦。因此,无需修改应用的状态逻辑,就可以替换为其他合成引擎。
我手动设置的快门和 ISO 会被记住吗?会。拍摄参数会通过 SharedPreferences 保存,下次打开应用时自动恢复。
大小
8.6 MB
星标
4.6K
更新
提交Aug 05
时长
3个月
提交 · 90 天