kinemotion 0.41.3__tar.gz → 0.42.0__tar.gz

kinemotion-0.42.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.42.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.42.0}/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!-- version list -->
 
+## 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.42.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kinemotion
-Version: 0.41.3
+Version: 0.42.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.42.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.42.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.42.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.42.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.42.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.42.0}/pyproject.toml

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

{kinemotion-0.41.3 → kinemotion-0.42.0}/uv.lock

@@ -894,7 +894,7 @@ wheels = [
 
 [[package]]
 name = "kinemotion"
-version = "0.41.3"
+version = "0.42.0"
 source = { editable = "." }
 dependencies = [
     { name = "click" },