rsheet 0.1.0__tar.gz

rsheet-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ELiijah-dev
+
+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.

rsheet-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: rsheet
+Version: 0.1.0
+Summary: Boîte à outils générique pour sprite sheets et animations 2D.
+Requires-Python: >=3.9
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: Pillow
+Requires-Dist: scipy
+Requires-Dist: pygame
+Dynamic: license-file
+Dynamic: requires-python

rsheet-0.1.0/README.md

@@ -0,0 +1,273 @@
+![Rsheet](assets/logo.jpg)
+
+**Rsheet** is a generic Python toolkit for 2D animation (background
+removal, sprite sheet splitting, size normalization, animation
+playback). It knows nothing about your specific game: it works just
+as well for a fighting game, a platformer, a physics simulation... any
+2D project that needs to animate sprites.
+
+**Why "Rsheet"?** It all starts with the sprite **sheet**: Rsheet
+analyzes it to automatically find where the frames are, in a few
+seconds, so you don't have to do it by hand.
+
+This README follows the full pipeline, in the order you'll use it on
+a real project: **1) clean the background, 2) split the frames,
+3) normalize the sizes, 4) play the animation**. All screenshots use
+the same example image, `penguin_walk.png`:
+
+![sprite sheet of a walking penguin](assets/penguin_walk.png)
+
+## Installation
+
+```bash
+pip install rsheet
+```
+
+No local compilation is needed (the only heavy computation,
+background detection, is delegated to `scipy`, distributed as
+precompiled wheels).
+
+## Try it now
+
+Clone the repo and run the example — it's ready to go, no setup
+needed:
+
+```bash
+git clone https://github.com/ELiijah-dev/rsheet.git
+cd rsheet/examples
+python demo.py
+```
+
+This opens a real pygame window playing a normalized, background-free
+animation, built end to end from a raw sprite sheet.
+
+---
+
+## Demo — what you'll see in your console
+
+This is exactly the script from step 4 below, run from VS Code:
+detection + splitting + normalization happen in a fraction of a
+second in the terminal, then the pygame window opens with the
+already-normalized animation ready to play.
+
+![console demo + pygame window](assets/console_demo_preview.gif)
+
+*(Compressed GIF for the preview — [full video with sound and detailed logs](assets/console_demo.mp4))*
+
+---
+
+## 1. `rsheet.cached_removed_bg` — isolating the character
+
+A developer who just wants to strip a background often makes the
+mistake of targeting *one* specific color (the corner pixel, say).
+That breaks the moment the background has a slight gradient,
+anti-aliasing noise, or changes from one asset to another. Rsheet
+therefore assumes nothing about the color: it looks at the pixels
+along the **edge** of the image, infers the two dominant colors
+(K-means), then floods outward from those edges through everything
+connected that resembles the background — following the actual
+outline rather than guessing its shape ahead of time.
+
+Concretely, `cached_removed_bg` returns a PNG with an alpha channel,
+keeping only the character. The result is cached next to the source
+file: the computation is only redone if the original image changes.
+
+The `tolerance` parameter exists because "resembles" has no universal
+answer: every sprite has its own level of noise around its edges, so
+it's a dial to tune per project rather than a value baked into
+Rsheet's code. The default is `40`, but **`6` is a good starting
+point** (raise it if background residue is still visible, lower it if
+chunks of the character disappear).
+
+```python
+import rsheet
+
+png_transparent = rsheet.cached_removed_bg("penguin_walk.png", tolerance=6)
+# -> penguin_walk._rsheet_bg_cache.png (background removed, ready to load in pygame)
+```
+
+| Before | After (`tolerance=6`) |
+|---|---|
+| ![before](assets/penguin_walk.png) | ![after](assets/penguin_walk_no_bg_t6.png) |
+
+---
+
+## 2. `rsheet.sprite_editor` — splitting and naming sprite sheets
+
+The real problem this module solves isn't "cutting up an image" — it's
+the time lost manually saying "this row has 6 frames, that one has 4,
+that other one has 8". Rsheet treats this as a pure geometry problem
+rather than a layout one: a row of non-background pixels is an
+animation, a column of non-background pixels inside that row is a
+frame. No grid is assumed, so it works the same on a neatly arranged
+sheet or one full of gaps.
+
+The random naming (`rsheet.vocab`) comes from a similar observation:
+giving each detected animation a meaningful name is still a manual
+task, while the code only needs a stable, unique key. Rsheet picks a
+random name and guarantees it never collides with another already
+used by that character — finding a free slot quickly rather than
+choosing one yourself.
+
+Concretely, `process_project` **automatically** detects the number of
+rows (animations) and frames per row — you never specify a frame
+count up front — then draws a unique name for each detected animation.
+The result is saved to a text file (`frame_coords.txt`) which is then
+used to build the in-game animation.
+
+```python
+import rsheet
+
+entries = rsheet.process_project(
+    "frame_coords.txt",
+    sheets=[
+        ("penguin_walk.png", "penguin", "player"),  # (file, character, role)
+    ],
+)
+
+for e in entries:
+    print(e.character, e.sheet_num, list(e.animations.keys()))
+# penguin 1 ['glide_a']   <- animation name drawn automatically
+```
+
+`role` (`"player"`, `"enemy"`, anything else, or `None`) is free-form —
+Rsheet never enforces it, it just stores it.
+
+---
+
+## 3. `rsheet.normalizer` — consistent on-screen sizes
+
+An artist never draws two frames at the exact same size — a raised
+wing takes up a bit more space than a lowered one, there's a few
+extra or missing pixels of empty space depending on the pose. If each
+frame were displayed as-is, the character would seem to slightly
+"float" or "jump" on every frame change, even while standing still.
+
+The normalizer fixes this by computing, for each frame, its offset
+from a common reference size — then always anchoring to the ground
+rather than the center, so that only a character's head moves on a
+small variation, never its feet. The result is cached and invalidated
+by a hash of the coordinates file, because this computation only ever
+needs redoing if the splitting changed — not on every game launch.
+
+Concretely, `load_or_compute_norm_cache` computes this offset for
+every frame and saves it to `frame_norm_cache.txt`:
+
+```python
+import pygame
+import rsheet
+
+norm = rsheet.load_or_compute_norm_cache(
+    "frame_coords.txt",
+    cache_path="frame_norm_cache.txt",
+)
+
+# frame_surface = the sub-image of one specific frame, cut from the
+# sheet at the coordinates found by sprite_editor in step 2 (this is
+# what `build_frame_cache`, in step 4, does for you automatically):
+sheet = pygame.image.load("penguin_walk.png").convert_alpha()
+frame_rect = entries[0].animations["glide_a"][0]  # `entries` comes from step 2
+frame_surface = sheet.subsurface(frame_rect.to_tuple()).copy()
+
+dw, dh = norm["penguin"]["glide_a"][0]
+surf = rsheet.apply_norm_to_surface(frame_surface, dw, dh)  # ground-anchored
+```
+
+> In practice, you'll almost never write this cutting logic by hand:
+> `build_frame_cache` (step 4) does exactly this, for every frame at
+> once.
+
+---
+
+## 4. `rsheet.animation` — building and playing the animation
+
+Steps 1 to 3 are deliberately "offline": they never touch `pygame`,
+know nothing about a game loop, and write their result to plain text
+files. `rsheet.animation` is the only module that bridges to the
+runtime — it's the one that turns pixel rectangles into actual
+`pygame.Surface` objects ready to be displayed. This separation exists
+so the expensive computation (detection, normalization) is never
+redone while the game is running.
+
+`AnimationController` stays deliberately "dumb": it only knows how to
+do one thing, advance a frame on a timer and loop — no fighting-game,
+platformer, or other gameplay logic gets mixed in, so it fits any
+project. `Entity` goes one step further by adding minimal physics
+(gravity, jumping, movement) because that's such a common need it was
+worth providing ready-made — but it stays optional: a project that
+already has its own physics can use only `AnimationController` and
+ignore `Entity`.
+
+Concretely, `build_frame_cache` loads the sprite sheet as a
+`pygame.Surface`, cuts each frame at the right spot and automatically
+applies the normalization computed in step 3 — you get back
+`{animation_name: [surfaces...]}` directly, ready to play with
+`AnimationController`:
+
+```python
+import pygame
+import rsheet
+
+pygame.init()
+screen = pygame.display.set_mode((640, 360))
+pygame.display.set_caption("Rsheet demo")
+clock = pygame.time.Clock()
+
+# Full pipeline (steps 1 to 3) — run once to prepare the files
+png_transparent = rsheet.cached_removed_bg("penguin_walk.png", tolerance=6)
+entries = rsheet.process_project(
+    "frame_coords.txt",
+    sheets=[(png_transparent, "penguin", "player")],
+)
+anim_name = list(entries[-1].animations.keys())[0]  # actual name generated in step 2
+sheet_num = entries[-1].sheet_num
+rsheet.load_or_compute_norm_cache("frame_coords.txt", cache_path="frame_norm_cache.txt")
+
+# Step 4 — build and play the animation
+frames = rsheet.build_frame_cache("penguin", {sheet_num: png_transparent}, "frame_coords.txt")
+anim = rsheet.AnimationController(frames=frames)
+anim.play(anim_name)
+
+x, y = 270, 115
+running = True
+while running:
+    for event in pygame.event.get():
+        if event.type == pygame.QUIT:
+            running = False
+
+    dt = clock.tick(60) / 1000
+    anim.update(dt)
+
+    screen.fill((40, 40, 40))
+    screen.blit(anim.current_surface(), (x, y))
+    pygame.display.flip()
+
+pygame.quit()
+```
+
+This script opens a real window and plays the animation on loop until
+closed — copy-pasteable as-is (just put `penguin_walk.png` next to the
+script, or swap in your own sprite sheet). This exact script is also
+available ready to run in `examples/demo.py` — see [Try it now](#try-it-now)
+above.
+
+For an entity with simple physics (movement, gravity, jumping),
+`Entity` embeds an `AnimationController` directly — replace the last
+two lines of the loop above with:
+
+```python
+hero = rsheet.Entity(anim=anim)
+hero.move(1)                        # moves to the right
+hero.update(dt, ground_y=300)       # physics + animation updated together
+screen.blit(anim.current_surface(), (hero.x, hero.y))
+```
+
+---
+
+## What else is in there?
+
+Rsheet also includes `rsheet.vfx` (generic light glow) and
+`rsheet.baking` (animation pre-computation, facing-direction handling,
+surface cropping/resizing) — useful once the 4 building blocks above
+are in place, but not essential to get started. See each module's
+docstrings for details.

rsheet-0.1.0/pyproject.toml

@@ -0,0 +1,10 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "rsheet"
+version = "0.1.0"
+description = "Boîte à outils générique pour sprite sheets et animations 2D."
+requires-python = ">=3.9"
+dependencies = ["numpy", "Pillow", "scipy", "pygame"]

rsheet-0.1.0/rsheet/__init__.py

@@ -0,0 +1,90 @@
+"""
+Rsheet — boîte à outils générique pour sprite sheets et animations 2D.
+
+Usage typique :
+
+    from rsheet.vocab import AnimVocabulary
+    from rsheet.sprite_editor import process_project
+
+    process_project(
+        "frame_coords.txt",
+        sheets=[
+            ("hero_1.png", "hero", "player"),
+            ("hero_2.png", "hero", "player"),
+            ("golem_1.png", "golem", "enemy"),
+        ],
+    )
+
+    from rsheet.animation import build_frame_cache, AnimationController, Entity
+    from rsheet.config import RsheetConfig
+
+    cfg = RsheetConfig.load("game_config.txt")
+    frames = build_frame_cache("hero", {1: "hero_1.png", 2: "hero_2.png"},
+                               "frame_coords.txt", "game_config.txt")
+
+    hero = Entity(config=cfg)
+    hero.anim.frames = frames
+    hero.anim.config = cfg
+    hero.anim.play("idle")
+"""
+
+from .vocab import AnimVocabulary, VocabExhaustedError
+from .config import RsheetConfig
+from .coords_io import SheetEntry, load_coords, save_coords
+from .detection import analyze_sheet, FrameRect, DetectedRow
+from .sprite_editor import add_sheet, process_project
+from .normalizer import (
+    load_or_compute_norm_cache,
+    apply_norm_to_surface,
+    load_norm_cache_file,
+    save_norm_cache_file,
+)
+from . import vfx
+from . import baking
+from .animation import AnimationController, Entity, build_frame_cache
+from .cache_utils import cached_removed_bg, cache_path_for
+from .parallel import precompute_backgrounds_parallel
+from .vfx import add_glow
+from .baking import (
+    bake_frames, precompute_mirrored, BakedCycle, mirror_angle_for_facing,
+    BurstPauseCycle, resolve_facing_sprite, DepletingScale,
+    slice_single_row, trim_and_scale,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "vfx",
+    "baking",
+    "AnimVocabulary",
+    "VocabExhaustedError",
+    "RsheetConfig",
+    "SheetEntry",
+    "load_coords",
+    "save_coords",
+    "analyze_sheet",
+    "FrameRect",
+    "DetectedRow",
+    "add_sheet",
+    "process_project",
+    "load_or_compute_norm_cache",
+    "apply_norm_to_surface",
+    "load_norm_cache_file",
+    "save_norm_cache_file",
+    "AnimationController",
+    "Entity",
+    "build_frame_cache",
+    "cached_removed_bg",
+    "cache_path_for",
+    "precompute_backgrounds_parallel",
+    "add_glow",
+    "bake_frames",
+    "precompute_mirrored",
+    "BakedCycle",
+    "mirror_angle_for_facing",
+    "BurstPauseCycle",
+    "resolve_facing_sprite",
+    "DepletingScale",
+    "slice_single_row",
+    "trim_and_scale",
+]

rsheet-0.1.0/rsheet/_fastops_fallback.py

@@ -0,0 +1,52 @@
+"""
+Fallback pur Python pour les opérations pixel-par-pixel de Rsheet.
+Utilisé automatiquement quand scipy n'est pas disponible. Fonctionnellement
+identique, juste plus lent.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+
+import numpy as np
+
+
+def flood_fill_bfs(arr_rgb: np.ndarray, bg1: np.ndarray, bg2: np.ndarray, tolerance: int) -> np.ndarray:
+    """BFS depuis les 4 bords de l'image pour marquer les pixels de fond.
+
+    Retourne un masque booléen (True = pixel de fond) de même taille
+    que l'image.
+    """
+    h, w = arr_rgb.shape[:2]
+    threshold = tolerance * 3
+    rgb = arr_rgb[:, :, :3].astype(np.int32)
+    d1 = np.abs(rgb - bg1).sum(axis=2)
+    d2 = np.abs(rgb - bg2).sum(axis=2)
+    maybe = (d1 < threshold) | (d2 < threshold)
+
+    visited = np.zeros((h, w), dtype=bool)
+    is_bg = np.zeros((h, w), dtype=bool)
+    q = deque()
+
+    for x in range(w):
+        for y in (0, h - 1):
+            if maybe[y, x] and not visited[y, x]:
+                visited[y, x] = is_bg[y, x] = True
+                q.append((y, x))
+    for y in range(h):
+        for x in (0, w - 1):
+            if maybe[y, x] and not visited[y, x]:
+                visited[y, x] = is_bg[y, x] = True
+                q.append((y, x))
+
+    dirs = ((-1, 0), (1, 0), (0, -1), (0, 1))
+    while q:
+        cy, cx = q.popleft()
+        for dy, dx in dirs:
+            ny, nx = cy + dy, cx + dx
+            if 0 <= ny < h and 0 <= nx < w and not visited[ny, nx]:
+                visited[ny, nx] = True
+                if maybe[ny, nx]:
+                    is_bg[ny, nx] = True
+                    q.append((ny, nx))
+    return is_bg

rsheet-0.1.0/rsheet/_scipy_ops.py

@@ -0,0 +1,46 @@
+"""
+Flood-fill de détection de fond, version scipy.
+
+Reformule le problème comme une recherche de composantes connexes,
+déjà résolue par scipy.ndimage.label (écrit en C, distribué en wheels
+précompilées pour toutes les plateformes — `pip install scipy` ne
+compile jamais rien chez l'utilisateur).
+
+Équivalence : un pixel est "fond" si (a) sa couleur est proche de l'une
+des deux couleurs de fond détectées, ET (b) il appartient à une région
+connexe (4-connectivité, comme le BFS) qui touche au moins un bord de
+l'image.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.ndimage import label, generate_binary_structure
+
+# 4-connectivité (haut/bas/gauche/droite), identique aux directions du BFS d'origine
+_STRUCT = generate_binary_structure(2, 1)
+
+
+def flood_fill_bfs(arr_rgb: np.ndarray, bg1: np.ndarray, bg2: np.ndarray, tolerance: int) -> np.ndarray:
+    """Retourne un masque booléen (True = pixel de fond), résultat
+    identique à un BFS depuis les 4 bords, calculé via composantes
+    connexes (scipy), sans aucune compilation requise."""
+    h, w = arr_rgb.shape[:2]
+    threshold = tolerance * 3
+    rgb = arr_rgb[:, :, :3].astype(np.int32)
+    d1 = np.abs(rgb - bg1).sum(axis=2)
+    d2 = np.abs(rgb - bg2).sum(axis=2)
+    maybe = (d1 < threshold) | (d2 < threshold)
+
+    labeled, n_labels = label(maybe, structure=_STRUCT)
+    if n_labels == 0:
+        return np.zeros((h, w), dtype=bool)
+
+    border_labels = set(labeled[0, :].tolist()) | set(labeled[-1, :].tolist())
+    border_labels |= set(labeled[:, 0].tolist()) | set(labeled[:, -1].tolist())
+    border_labels.discard(0)  # 0 = pixels hors du masque `maybe`, pas une vraie composante
+
+    if not border_labels:
+        return np.zeros((h, w), dtype=bool)
+
+    return np.isin(labeled, list(border_labels))