kinemotion 0.41.3__tar.gz → 0.43.0__tar.gz

kinemotion-0.43.0/.basic-memory/api/cloud-run-cpu-specifications-investigation.md

@@ -0,0 +1,38 @@
+---
+title: Cloud Run CPU Specifications Investigation
+type: note
+permalink: api/cloud-run-cpu-specifications-investigation
+tags:
+- cloud-run
+- infrastructure
+- cpu-specs
+---
+
+## Cloud Run 1 CPU & 4GB RAM Configuration
+
+### Key Finding: Cloud Run Abstracts Infrastructure Details
+
+Cloud Run does **not** publicly expose specific CPU processor details (family, generation, clock speed) for its container instances. This is by design - Cloud Run prioritizes abstraction over infrastructure visibility.
+
+### What We Know:
+- **Default CPU limit**: 1 CPU
+- **Max memory with 1 CPU**: 4 GiB (matches user config)
+- **Allocation model**: vCPU (virtual CPU, not pinned to physical core)
+- **Underlying platform**: Runs on Google Cloud infrastructure (likely shares hardware with Compute Engine)
+
+### Compute Engine CPU Options (for reference):
+Cloud Run doesn't let you choose, but Compute Engine uses:
+- **Intel Xeon processors** (Skylake through Granite Rapids generations)
+  - Base frequencies: 1.9 - 3.1 GHz depending on generation
+  - Turbo frequencies: 2.6 - 4.2 GHz
+- **AMD EPYC processors** (Rome through Turin generations)
+  - Base frequencies: 2.25 - 2.7 GHz
+  - Max boost: 3.3 - 4.1 GHz
+
+### To Determine Actual Hardware:
+1. **CPU info from OS**: `lscpu` or `/proc/cpuinfo` inside container (reveals actual hypervisor CPU)
+2. **Runtime profiling**: Use CPU benchmarks to infer processor type
+3. **Google docs**: No official specification available - intentionally abstracted
+
+### Practical Implication:
+You cannot guarantee a specific processor family or clock speed in Cloud Run. Google allocates based on availability and load balancing across their infrastructure.

{kinemotion-0.41.3 → kinemotion-0.43.0}/.basic-memory/project-management/performance-optimization-pose-tracker-pool-timing-instrumentation-complete.md

@@ -221,3 +221,53 @@ if json_output:
 - **Linting**: 0 errors (ruff)
 - **Duplicat code**: < 3% (maintained)
 - **Git commits**: Conventional format with full context
+
+
+## Production Validation (2025-12-10)
+
+### Request Analysis
+- **Request ID**: f2316e09-cc7d-4a53-98db-27a343dac7e0
+- **Total Duration**: 278.8 seconds (278,249.09 ms)
+- **Status**: ✅ Success (200 OK)
+
+### Confirmed Timing Breakdown
+
+| Stage | Duration | % of Total |
+|-------|----------|-----------|
+| Debug video generation | 254.8s | 91.4% |
+| Pose tracking | 15.5s | 5.6% |
+| R2 debug video upload | 3.4s | 1.2% |
+| R2 results upload | 0.9s | 0.3% |
+| Smoothing | 0.3s | 0.1% |
+| Parameter auto-tuning | 2.8ms | <0.1% |
+| Other stages | 3.9s | 1.4% |
+
+### Validation Results
+
+✅ **PoseTracker Pool**: Successfully reused across request - no re-initialization overhead
+✅ **Timing Instrumentation**: Capturing 100% of processing pipeline
+✅ **Root Cause Identified**: Debug video generation is 91.4% of total time (expected)
+✅ **All Time Accounted For**: Previous 370-second gap is now fully instrumented
+
+### Analysis
+
+The performance fixes are working correctly in production:
+
+1. **Pool Efficiency**: MediaPipe Pose model not reloaded per request
+2. **Complete Visibility**: All stages now measured with proper timing
+3. **Expected Cost**: Debug video rendering is inherently expensive:
+   - Processes every frame in sequence
+   - Renders pose skeleton + landmarks overlay
+   - Encodes to video format
+   - Uploads to cloud storage (3.4s network time)
+
+### Next Steps
+
+The timing is now fully visible. Future optimization opportunities:
+
+1. **Async debug video generation** - Could return results immediately while rendering continues
+2. **Parallel uploads** - R2 upload could happen while generating video
+3. **Optional debug video** - Make debug video generation opt-in for faster responses
+4. **Frame sampling** - Render every Nth frame for faster preview generation
+
+However, the current performance is acceptable for the use case. All 278 seconds are accounted for and the PoseTracker pool optimization is delivering value by eliminating tracker re-initialization costs.

{kinemotion-0.41.3 → kinemotion-0.43.0}/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## v0.43.0 (2025-12-11)
+
+### Continuous Integration
+
+- Remove b ad workflow
+  ([`7584229`](https://github.com/feniix/kinemotion/commit/7584229682eb94ddf13a6becac7ad31b96d62f0f))
+
+### Features
+
+- Optimize debug video generation and improve code quality
+  ([`81ce698`](https://github.com/feniix/kinemotion/commit/81ce698d5a0fa8dff6c20c6870a7bee52080cef0))
+
+### Testing
+
+- Optimize test suite execution speed
+  ([`26ea210`](https://github.com/feniix/kinemotion/commit/26ea21072745ef606405b5f6f5277dd422636baf))
+
+
+## v0.42.0 (2025-12-10)
+
+### Documentation
+
+- Add some more docs about cpu settings
+  ([`ebd0f5b`](https://github.com/feniix/kinemotion/commit/ebd0f5b2c9e1b25a9c95d04b32c35f27560f3584))
+
+- Performance-optimization-pose-tracker-pool
+  ([`c1b2e76`](https://github.com/feniix/kinemotion/commit/c1b2e7665371e8384261044a4f3e10202df78dc2))
+
+### Features
+
+- Add debug toggle for optional video overlay generation
+  ([`afd0b49`](https://github.com/feniix/kinemotion/commit/afd0b496d3c33d9428c71d417b9cb4b18a5dd9cc))
+
+
 ## v0.41.3 (2025-12-10)
 
 ### Bug Fixes

{kinemotion-0.41.3 → kinemotion-0.43.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.41.3
+Version: 0.43.0
 Summary: Video-based kinematic analysis for athletic performance
 Project-URL: Homepage, https://github.com/feniix/kinemotion
 Project-URL: Repository, https://github.com/feniix/kinemotion

{kinemotion-0.41.3 → kinemotion-0.43.0}/backend/src/kinemotion_backend/app.py

@@ -507,6 +507,7 @@ async def analyze_video(
     file: UploadFile = File(...),  # noqa: B008
     jump_type: str = Form("cmj"),  # noqa: B008
     quality: str = Form("balanced"),  # noqa: B008
+    debug: str = Form("false"),  # noqa: B008
     referer: str | None = Header(None),  # noqa: B008
     x_test_password: str | None = Header(None),  # noqa: B008
 ) -> JSONResponse:
@@ -520,6 +521,7 @@ async def analyze_video(
         file: Video file to analyze (multipart/form-data)
         jump_type: Type of jump ("drop_jump" or "cmj")
         quality: Analysis quality preset ("fast", "balanced", or "accurate")
+        debug: Debug overlay flag ("true" or "false", default "false")
 
     Returns:
         JSON response with metrics or error details
@@ -572,9 +574,14 @@ async def analyze_video(
             save_duration = time.time() - save_start
         logger.info("timing_video_file_save", duration_ms=round(save_duration * 1000))
 
-        # Create temporary path for debug video output
-        with tempfile.NamedTemporaryFile(suffix=".mp4", delete=False) as temp_debug:
-            temp_debug_video_path = temp_debug.name
+        # Convert debug string to boolean
+        enable_debug = debug.lower() == "true"
+
+        # Create temporary path for debug video output (only if debug enabled)
+        temp_debug_video_path = None
+        if enable_debug:
+            with tempfile.NamedTemporaryFile(suffix=".mp4", delete=False) as temp_debug:
+                temp_debug_video_path = temp_debug.name
 
         # Upload to R2 if client available
         if r2_client:
@@ -611,7 +618,7 @@ async def analyze_video(
             temp_video_path,
             jump_type,
             quality,
-            output_video=temp_debug_video_path,
+            output_video=temp_debug_video_path if enable_debug else None,
             timer=timer,
             pose_tracker=pose_tracker,
         )  # type: ignore[arg-type]

{kinemotion-0.41.3 → kinemotion-0.43.0}/frontend/src/App.tsx

@@ -11,7 +11,7 @@ import { useBackendVersion } from './hooks/useBackendVersion'
 
 function App() {
   const { user, loading: authLoading, signOut } = useAuth()
-  const { file, jumpType, loading, uploadProgress, metrics, error, setFile, setJumpType, analyze, retry } = useAnalysis()
+  const { file, jumpType, loading, uploadProgress, metrics, error, enableDebug, setFile, setJumpType, setEnableDebug, analyze, retry } = useAnalysis()
   const { recentUploads, addRecentUpload, clearRecentUploads } = useRecentUploads()
   const { backendVersion, kinemotionVersion } = useBackendVersion()
 
@@ -70,9 +70,11 @@ function App() {
           file={file}
           jumpType={jumpType}
           loading={loading}
+          enableDebug={enableDebug}
           recentUploads={recentUploads}
           onFileChange={setFile}
           onJumpTypeChange={setJumpType}
+          onEnableDebugChange={setEnableDebug}
           onAnalyze={handleAnalyze}
           onClearHistory={clearRecentUploads}
         />

{kinemotion-0.41.3 → kinemotion-0.43.0}/frontend/src/components/UploadForm.tsx

@@ -6,9 +6,11 @@ interface UploadFormProps {
   file: File | null
   jumpType: 'cmj' | 'dropjump'
   loading: boolean
+  enableDebug: boolean
   recentUploads: RecentUpload[]
   onFileChange: (file: File | null) => void
   onJumpTypeChange: (jumpType: 'cmj' | 'dropjump') => void
+  onEnableDebugChange: (enable: boolean) => void
   onAnalyze: () => void
   onClearHistory?: () => void
 }
@@ -19,9 +21,11 @@ function UploadForm({
   file,
   jumpType,
   loading,
+  enableDebug,
   recentUploads,
   onFileChange,
   onJumpTypeChange,
+  onEnableDebugChange,
   onAnalyze,
   onClearHistory,
 }: UploadFormProps) {
@@ -157,6 +161,25 @@ function UploadForm({
         </select>
       </div>
 
+      <div className="form-group checkbox-group">
+        <label htmlFor="enable-debug" className="checkbox-label">
+          <input
+            id="enable-debug"
+            type="checkbox"
+            checked={enableDebug}
+            onChange={(e) => onEnableDebugChange(e.target.checked)}
+            disabled={loading}
+            className="checkbox-input"
+          />
+          <span>Enable debug video overlay</span>
+        </label>
+        <p className="checkbox-hint">
+          {enableDebug
+            ? 'Debug video will be generated and available for download (~4-5 min slower)'
+            : 'Results only (faster analysis ~20 seconds)'}
+        </p>
+      </div>
+
       <button
         className="analyze-button"
         onClick={onAnalyze}

{kinemotion-0.41.3 → kinemotion-0.43.0}/frontend/src/hooks/useAnalysis.ts

@@ -9,11 +9,13 @@ interface UseAnalysisState {
   uploadProgress: number
   metrics: AnalysisResponse | null
   error: string | null
+  enableDebug: boolean
 }
 
 interface UseAnalysisActions {
   setFile: (file: File | null) => void
   setJumpType: (jumpType: JumpType) => void
+  setEnableDebug: (enable: boolean) => void
   analyze: () => Promise<void>
   retry: () => Promise<void>
   reset: () => void
@@ -30,6 +32,7 @@ export function useAnalysis(): UseAnalysisState & UseAnalysisActions {
   const [uploadProgress, setUploadProgress] = useState(0)
   const [metrics, setMetrics] = useState<AnalysisResponse | null>(null)
   const [error, setError] = useState<string | null>(null)
+  const [enableDebug, setEnableDebug] = useState(false)
 
   const analyze = async () => {
     if (!file) {
@@ -47,6 +50,7 @@ export function useAnalysis(): UseAnalysisState & UseAnalysisActions {
     // Convert frontend format (cmj/dropjump) to backend format (cmj/drop_jump)
     const backendJumpType = jumpType === 'dropjump' ? 'drop_jump' : jumpType
     formData.append('jump_type', backendJumpType)
+    formData.append('debug', enableDebug ? 'true' : 'false')
 
     try {
       // Use environment variable for API URL in production, or relative proxy in development
@@ -134,6 +138,7 @@ export function useAnalysis(): UseAnalysisState & UseAnalysisActions {
     setUploadProgress(0)
     setMetrics(null)
     setError(null)
+    setEnableDebug(false)
   }
 
   return {
@@ -144,9 +149,11 @@ export function useAnalysis(): UseAnalysisState & UseAnalysisActions {
     uploadProgress,
     metrics,
     error,
+    enableDebug,
     // Actions
     setFile,
     setJumpType,
+    setEnableDebug,
     analyze,
     retry,
     reset,

{kinemotion-0.41.3 → kinemotion-0.43.0}/frontend/src/index.css

@@ -603,6 +603,39 @@ body {
   transform: translateY(-1px);
 }
 
+/* Checkbox group */
+.checkbox-group {
+  margin-bottom: 1.5rem;
+}
+
+.checkbox-label {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  cursor: pointer;
+  font-weight: 500;
+  margin-bottom: 0.5rem;
+}
+
+.checkbox-input {
+  width: 18px;
+  height: 18px;
+  cursor: pointer;
+  accent-color: var(--primary-color);
+}
+
+.checkbox-input:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.checkbox-hint {
+  margin: 0.5rem 0 0 1.75rem;
+  font-size: 0.85rem;
+  color: var(--text-secondary);
+  font-weight: normal;
+}
+
 /* Animations */
 @keyframes fadeIn { from { opacity: 0; transform: translateY(10px); } to { opacity: 1; transform: translateY(0); } }
 .animate-fade-in { animation: fadeIn 0.4s ease-out forwards; }

{kinemotion-0.41.3 → kinemotion-0.43.0}/justfile

@@ -1,3 +1,14 @@
+# Check python sanity
+python-check:
+    @echo "Running pyright..."
+    uv run pyright
+    (cd backend && uv run pyright)
+    @echo "Running ruff check and format..."
+    uv run ruff check --fix
+    uv run ruff format
+    (cd backend && uv run ruff check --fix)
+    (cd backend && uv run ruff format)
+
 # Clean generated and temporary files (preserves .claude/, .cursor/, .mcp.json)
 clean:
     @echo "Cleaning generated files..."

{kinemotion-0.41.3 → kinemotion-0.43.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kinemotion"
-version = "0.41.3"
+version = "0.43.0"
 description = "Video-based kinematic analysis for athletic performance"
 readme = "README.md"
 requires-python = ">=3.10,<3.13"

{kinemotion-0.41.3 → kinemotion-0.43.0}/src/kinemotion/api.py

@@ -1,4 +1,4 @@
-"""Public API for programmatic use of kinemotion analysis."""
+"Public API for programmatic use of kinemotion analysis."
 
 import time
 from collections.abc import Callable
@@ -37,7 +37,6 @@ from .core.smoothing import smooth_landmarks, smooth_landmarks_advanced
 from .core.timing import PerformanceTimer
 from .core.video_io import VideoProcessor
 from .dropjump.analysis import (
-    ContactState,
     compute_average_foot_position,
     detect_ground_contact,
     find_contact_phases,
@@ -370,105 +369,15 @@ def _convert_timer_to_stage_names(
         "json_serialization": "JSON serialization",
         "debug_video_generation": "Debug video generation",
         "debug_video_reencode": "Debug video re-encoding",
+        "frame_rotation": "Frame rotation",
+        "debug_video_resize": "Debug video resizing",
+        "debug_video_copy": "Debug video frame copy",
+        "debug_video_draw": "Debug video drawing",
+        "debug_video_write": "Debug video encoding",
     }
     return {mapping.get(k, k): v for k, v in timer_metrics.items()}
 
 
-def _generate_dropjump_outputs(
-    metrics: DropJumpMetrics,
-    json_output: str | None,
-    output_video: str | None,
-    frames: list,
-    smoothed_landmarks: list,
-    contact_states: list[ContactState],
-    video: VideoProcessor,
-    verbose: bool,
-    timer: PerformanceTimer | None = None,
-) -> None:
-    """Generate JSON and debug video outputs if requested.
-
-    Args:
-        metrics: Calculated drop jump metrics
-        json_output: Optional path for JSON output
-        output_video: Optional path for debug video
-        frames: List of video frames
-        smoothed_landmarks: Smoothed landmark sequence
-        contact_states: Ground contact state for each frame
-        video: Video processor with dimensions and fps
-        verbose: Print progress messages
-        timer: Optional PerformanceTimer for measuring operations
-    """
-    # Save JSON if requested
-    if json_output:
-        import json
-
-        if timer:
-            with timer.measure("json_serialization"):
-                output_path = Path(json_output)
-                metrics_dict = metrics.to_dict()
-                json_str = json.dumps(metrics_dict, indent=2)
-                output_path.write_text(json_str)
-        else:
-            output_path = Path(json_output)
-            metrics_dict = metrics.to_dict()
-            json_str = json.dumps(metrics_dict, indent=2)
-            output_path.write_text(json_str)
-
-        if verbose:
-            print(f"Metrics written to: {json_output}")
-
-    # Generate debug video if requested
-    if output_video:
-        if verbose:
-            print(f"Generating debug video: {output_video}")
-
-        if timer:
-            with timer.measure("debug_video_generation"):
-                with DebugOverlayRenderer(
-                    output_video,
-                    video.width,
-                    video.height,
-                    video.display_width,
-                    video.display_height,
-                    video.fps,
-                ) as renderer:
-                    for i, frame in enumerate(frames):
-                        annotated = renderer.render_frame(
-                            frame,
-                            smoothed_landmarks[i],
-                            contact_states[i],
-                            i,
-                            metrics,
-                            use_com=False,
-                        )
-                        renderer.write_frame(annotated)
-            # Capture re-encoding duration separately
-            with timer.measure("debug_video_reencode"):
-                pass  # Re-encoding happens in context manager __exit__
-        else:
-            with DebugOverlayRenderer(
-                output_video,
-                video.width,
-                video.height,
-                video.display_width,
-                video.display_height,
-                video.fps,
-            ) as renderer:
-                for i, frame in enumerate(frames):
-                    annotated = renderer.render_frame(
-                        frame,
-                        smoothed_landmarks[i],
-                        contact_states[i],
-                        i,
-                        metrics,
-                        use_com=False,
-                    )
-                    renderer.write_frame(annotated)
-
-        if verbose:
-            print(f"Debug video saved: {output_video}")
-
-
 @dataclass
 class DropJumpVideoResult:
     """Result of processing a single drop jump video."""
@@ -740,6 +649,7 @@ def process_dropjump_video(
                             video.display_width,
                             video.display_height,
                             video.fps,
+                            timer=timer,
                         ) as renderer:
                             for i, frame in enumerate(frames):
                                 annotated = renderer.render_frame(
@@ -762,6 +672,7 @@ def process_dropjump_video(
                         video.display_width,
                         video.display_height,
                         video.fps,
+                        timer=timer,
                     ) as renderer:
                         for i, frame in enumerate(frames):
                             annotated = renderer.render_frame(
@@ -843,7 +754,7 @@ def process_dropjump_video(
                     dur_ms = duration * 1000
                     print(f"{stage:.<40} {dur_ms:>6.0f}ms ({percentage:>5.1f}%)")
                 total_ms = total_time * 1000
-                print(f"{'Total':.>40} {total_ms:>6.0f}ms (100.0%)")
+                print(f"{('Total'):.>40} {total_ms:>6.0f}ms (100.0%)")
                 print()
                 print("Analysis complete!")
 
@@ -994,95 +905,6 @@ class CMJVideoResult:
     processing_time: float = 0.0
 
 
-def _generate_cmj_outputs(
-    output_video: str | None,
-    json_output: str | None,
-    metrics: CMJMetrics,
-    frames: list,
-    smoothed_landmarks: list,
-    video_width: int,
-    video_height: int,
-    video_display_width: int,
-    video_display_height: int,
-    video_fps: float,
-    verbose: bool,
-    timer: PerformanceTimer | None = None,
-) -> None:
-    """Generate JSON and debug video outputs for CMJ analysis.
-
-    Args:
-        output_video: Optional path for debug video output
-        json_output: Optional path for JSON output
-        metrics: Calculated CMJ metrics
-        frames: List of video frames
-        smoothed_landmarks: Smoothed landmark sequence
-        video_width: Video width in pixels
-        video_height: Video height in pixels
-        video_display_width: Display width considering aspect ratio
-        video_display_height: Display height considering aspect ratio
-        video_fps: Video frames per second
-        verbose: Print progress messages
-        timer: Optional PerformanceTimer for measuring operations
-    """
-    if json_output:
-        import json
-
-        if timer:
-            with timer.measure("json_serialization"):
-                output_path = Path(json_output)
-                metrics_dict = metrics.to_dict()
-                json_str = json.dumps(metrics_dict, indent=2)
-                output_path.write_text(json_str)
-        else:
-            output_path = Path(json_output)
-            metrics_dict = metrics.to_dict()
-            json_str = json.dumps(metrics_dict, indent=2)
-            output_path.write_text(json_str)
-
-        if verbose:
-            print(f"Metrics written to: {json_output}")
-
-    if output_video:
-        if verbose:
-            print(f"Generating debug video: {output_video}")
-
-        if timer:
-            with timer.measure("debug_video_generation"):
-                with CMJDebugOverlayRenderer(
-                    output_video,
-                    video_width,
-                    video_height,
-                    video_display_width,
-                    video_display_height,
-                    video_fps,
-                ) as renderer:
-                    for i, frame in enumerate(frames):
-                        annotated = renderer.render_frame(
-                            frame, smoothed_landmarks[i], i, metrics
-                        )
-                        renderer.write_frame(annotated)
-            # Capture re-encoding duration separately
-            with timer.measure("debug_video_reencode"):
-                pass  # Re-encoding happens in context manager __exit__
-        else:
-            with CMJDebugOverlayRenderer(
-                output_video,
-                video_width,
-                video_height,
-                video_display_width,
-                video_display_height,
-                video_fps,
-            ) as renderer:
-                for i, frame in enumerate(frames):
-                    annotated = renderer.render_frame(
-                        frame, smoothed_landmarks[i], i, metrics
-                    )
-                    renderer.write_frame(annotated)
-
-        if verbose:
-            print(f"Debug video saved: {output_video}")
-
-
 def process_cmj_video(
     video_path: str,
     quality: str = "balanced",
@@ -1340,6 +1162,7 @@ def process_cmj_video(
                             video.display_width,
                             video.display_height,
                             video.fps,
+                            timer=timer,  # Passing timer here too
                         ) as renderer:
                             for i, frame in enumerate(frames):
                                 annotated = renderer.render_frame(
@@ -1357,6 +1180,7 @@ def process_cmj_video(
                         video.display_width,
                         video.display_height,
                         video.fps,
+                        timer=timer,  # Passing timer here too
                     ) as renderer:
                         for i, frame in enumerate(frames):
                             annotated = renderer.render_frame(
@@ -1433,7 +1257,7 @@ def process_cmj_video(
                     dur_ms = duration * 1000
                     print(f"{stage:.<40} {dur_ms:>6.0f}ms ({percentage:>5.1f}%)")
                 total_ms = total_time * 1000
-                print(f"{'Total':.>40} {total_ms:>6.0f}ms (100.0%)")
+                print(f"{('Total'):.>40} {total_ms:>6.0f}ms (100.0%)")
                 print()
 
                 print(f"\nJump height: {metrics.jump_height:.3f}m")