ANIMA

Anima

Anima is a Python framework for Blender focused on mathematical visualizations, procedural animations, and educational content. It provides tools for animating curves, rendering LaTeX text, managing scenes, and supporting a streamlined development workflow.

Features

• Tools for animating curves, splines, and geometric objects
• LaTeX text rendering as animated 3D glyphs
• Bézier spline and curve utilities
• Automated scene setup and cleanup
• Hot reload support for rapid development

Prerequisites

• uv (Python package manager)
• GNU Make (for building, testing, and running)
• Python 3.11+ (specifically 3.11.4 - 3.11.13 for Blender compatibility)
• Blender (4.0+ recommended)
• Visual Studio Code (optional, but recommended for development)

Installation

1. Clone the Repository

   git clone https://github.com/8bit-euclid/Anima.git
   cd Anima

2. Configure Blender Settings

   Edit pyproject.toml to specify your Blender version and installation directory:

   [tool.blender]
   version = "4.5.3"
   install-dir = "~/Applications/blender/"

   Note: Your Blender directory must follow the naming convention blender-{version}-{platform} (e.g., blender-4.5.3-linux-x64)

3. Install the Project

   make install

Verification

After installation, verify the setup by running tests:

make test

Make Targets

The project includes several make targets for common development tasks. Run make help to see all available targets, or use these essential commands:

Command	Description
make help	Show all available targets with descriptions
make install	Install the project and its dependencies
make install-dev	Install the project in development mode
make install-blender-deps	Install Blender-specific dependencies
make run	Run the project
make test	Run all tests
make format	Format code using black and isort
make lint	Lint the project using pylint and flake8
make clean	Clean build artifacts and cache files
make all	Run the complete workflow (clean, format, lint, install, and test)

Upgrading Blender

To upgrade to a new Blender version:

1. Install the new Blender version following the naming convention
2. Update version = "4.6.0" in pyproject.toml
3. Run make install

The system automatically updates the bpy dependency and paths to match.

Development Workflows

Running Anima with Blender

To start Blender using the Blender Development extension in Visual Studio Code:

make run

1. Open the Anima project folder in VSCode and navigate to the run.py file.
2. Select Blender: Start from the command palette (Ctrl+Shift+P → "Blender: Start").
3. When prompted, select the Blender executable from your installation directory.
4. Blender will launch with the current project loaded, enabling rapid development and testing.
5. Run anima in Blender by selecting Blender: Run Script from the command palette (Ctrl+Shift+P → "Blender: Run Script").
6. Repeat step 5 to hot-reload recent changes into Blender.

Optional: Set a Key Binding for "Blender: Run Script"

To streamline step 5, you can assign a custom key binding (e.g., Ctrl+Shift+B) to the Blender: Run Script command in VSCode:

1. Open the command palette (Ctrl+Shift+P) and search for "Preferences: Open Keyboard Shortcuts".
2. In the search bar, type Blender: Run Script.
3. Click the pencil icon next to the command and press your desired key combination (e.g. Ctrl+Shift+B).
4. Press Enter to save the key binding.

Now, you can quickly hot-reload recent changes in Blender using your chosen shortcut.

Logging

Anima includes a built-in logging system powered by loguru that provides structured, colorized output for debugging and monitoring.

Configuration

The logger can be configured using environment variables:

• ANIMA_LOG_LEVEL: Set the logging level (default: DEBUG)
  • Options: TRACE, DEBUG, INFO, WARNING, ERROR, CRITICAL
• ANIMA_LOG_SHOW_FUNCTION: Show function names in logs (default: 0)
  • Set to 1 to enable
• ANIMA_LOG_SHOW_PROCESS: Show process and thread IDs (default: 0)
  • Set to 1 to enable

Usage

Import and use the logger in your code:

from anima.diagnostics import logger, format_output

# Basic logging examples
logger.trace("This is a trace message")
logger.info("Animation started")
logger.debug("Processing curve data")
logger.warning("Texture not found, using default")
logger.error("Failed to load mesh")

# Format output with title
output = format_output("Render Settings", "Resolution: 1920x1080\nSamples: 128")
logger.info(output)

To configure logging behavior, set the environment variables before running Anima.

On Linux/macOS:

export ANIMA_LOG_LEVEL=INFO
export ANIMA_LOG_SHOW_FUNCTION=1
make run

Alternatively, set them immediately before the run command:

ANIMA_LOG_LEVEL=INFO ANIMA_LOG_SHOW_FUNCTION=1 make run

Status

This project is a work in progress. Usage instructions and examples will be sporadically added as development progresses.

---