docs: Readme read animation

.gitignore

@@ -1,5 +1,4 @@
-# Generated by Cargo
-# will have compiled files and executables
+# Compiled files and executables
 debug
 target
 
@@ -8,3 +7,13 @@ target
 
 # Debug artifacts
 *.vgcore
+heaptrack.*
+
+# Python artifacts
+.venv/
+*.pyc
+
+# Local animation tooling
+generated/
+.media/
+.frames/

README.md

@@ -24,6 +24,10 @@ SparseIO is a Rust library for sparse, out-of-order materialization of large byt
 
 Instead of eagerly copying an entire object from source to destination, SparseIO allows you to fetch only the chunks you ask for. It tracks what is already present for efficient caching, and deduplicates concurrent reads for the same chunk.
 
+<p align="center">
+<img width="600px" src="./docs/static/general-read.gif">
+</p>
+
 ## Core Premise
 
 Certain large data objects, such as multimedia files, system logs, columnar storage files used in AI and ML workloads, and archival records, are often accessed non-sequentially. In these scenarios, applications typically retrieve only specific byte ranges rather than reading the entire object. Loading all bytes upfront results in unnecessary I/O, increased latency, and inefficient bandwidth utilization. Selective or partial reads improve performance by reducing data transfer, accelerating processing, and optimizing resource consumption.

scripts/animations/README.md

@@ -0,0 +1,30 @@
+# Animations
+
+This directory holds short `manim` scenes used to generate README-friendly animations for SparseIO.
+
+## Layout
+
+- `general-read/`: shows the core sparse read path for buffered and streamed viewer reads.
+
+## Setup
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install --upgrade pip
+python3 -m pip install manim==0.19.0
+```
+
+`ffmpeg` is also required for GIF output.
+
+## Rendering
+
+Render animation:
+
+```bash
+./scripts/animations/{animation}/render.sh
+```
+
+```text
+docs/static/{animation}.gif
+```

scripts/animations/common.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ANIMATIONS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "$ANIMATIONS_DIR/../.." && pwd)"
+VENV_DIR="$ANIMATIONS_DIR/.venv"
+PYTHON_BIN="$VENV_DIR/bin/python3"
+REQUIREMENTS_FILE="$ANIMATIONS_DIR/requirements.txt"
+
+ensure_animation_venv() {
+  if [[ ! -x "$PYTHON_BIN" ]]; then
+    echo "creating animation virtualenv at $VENV_DIR" >&2
+    python3 -m venv "$VENV_DIR"
+    "$PYTHON_BIN" -m pip install --upgrade pip
+    "$PYTHON_BIN" -m pip install -r "$REQUIREMENTS_FILE"
+  fi
+}
+
+ensure_animation_venv

scripts/animations/general-read/render.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ANIMATION_NAME="general-read"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../common.sh"
+
+SCENE_FILE="$ROOT_DIR/scripts/animations/$ANIMATION_NAME/scene.py"
+MEDIA_DIR="$ROOT_DIR/scripts/animations/$ANIMATION_NAME/.media"
+OUTPUT_DIR="$ROOT_DIR/docs/static"
+OUTPUT_GIF="$OUTPUT_DIR/$ANIMATION_NAME.gif"
+
+mkdir -p "$MEDIA_DIR" "$OUTPUT_DIR"
+
+"$PYTHON_BIN" -m manim -q l --fps 12 --media_dir "$MEDIA_DIR" "$SCENE_FILE" GeneralReadScene
+
+VIDEO_FILE="$(find "$MEDIA_DIR/videos" -type f -name 'GeneralReadScene.mp4' | head -n 1)"
+if [[ -z "$VIDEO_FILE" ]]; then
+  echo "rendered video not found under $MEDIA_DIR/videos" >&2
+  exit 1
+fi
+
+ffmpeg -y \
+  -i "$VIDEO_FILE" \
+  -vf "fps=12,scale=960:-1:flags=lanczos,split[s0][s1];[s0]palettegen=max_colors=128[p];[s1][p]paletteuse=dither=bayer:bayer_scale=3" \
+  "$OUTPUT_GIF"
+
+echo "wrote $OUTPUT_GIF"