Bioxel/AGENTS.md

BioxelNodes - Agent Development Guide

This file contains essential information for agentic coding agents working on the BioxelNodes codebase.

Project Overview

BioxelNodes is a Blender addon for scientific volumetric data visualization. It integrates with Blender's Geometry Nodes and Cycles rendering engine to process and visualize medical/scientific data.

Language: Python 3.11 Framework: Blender Python API (bpy) Package Manager: uv

Development Commands

Environment Setup

# Install dependencies
uv sync

Build Commands

# Build for specific platform
uv run build.py <platform>  # platforms: windows-x64, linux-x64, macos-arm64, macos-x64

Unit Test

uv run pytest tests/

Code Quality

# Format code (autopep8)
autopep8 --in-place --recursive src/

Documentation

# Serve documentation locally
uv run mkdocs serve

# Build documentation
uv run mike deploy --push --update-aliases 0.2.x latest

Code Style Guidelines

Formatting

• 4-space indentation
• PEP 8 compliance enforced via autopep8

Naming Conventions

• snake_case for functions, variables, and files
• PascalCase for classes (Blender convention)
• UPPER_CASE for constants
• bioxel_ prefix for addon-specific properties

Import Organization

# Standard library imports first
import pathlib
import uuid

# Third-party imports
import bpy
import numpy as np
import SimpleITK as sitk

# Relative imports for internal modules
from ..exceptions import CancelledByUser
from ..utils import get_layer_obj

Type Hints

• Use sparingly, mainly for Blender property annotations
• Focus on function signatures and complex data structures
• Example: def process_data(data: np.ndarray) -> np.ndarray:

Architecture Patterns

Auto-Registration System

• Uses auto_load.py for automatic class registration
• Classes are discovered automatically via reflection
• Registration order resolved via topological sorting
• All Blender classes must inherit from appropriate base types

Module Structure

src/bioxelnodes/
├── __init__.py           # Addon entry point, asset library setup
├── auto_load.py          # Auto-registration system
├── constants.py          # Constants and paths
├── utils.py              # Utility functions
├── preferences.py        # Addon preferences
├── props.py              # Blender properties
├── panels.py             # UI panels
├── menus.py              # UI menus
├── node.py               # Node utilities
├── layer.py              # Layer management
├── operators/            # Blender operators
├── bioxel/               # Core bioxel functionality
└── assets/               # Blender assets and node libraries

Blender Integration Patterns

Property Groups

class BioxelProperties(bpy.types.PropertyGroup):
    bl_label = "Bioxel Properties"
    
    bioxel_custom_prop: bpy.props.StringProperty(
        name="Custom Property",
        default="",
        description="Description for UI"
    )

Operators

class BIOXEL_OT_custom_operator(bpy.types.Operator):
    bl_idname = "bioxel.custom_operator"
    bl_label = "Custom Operator"
    bl_options = {'REGISTER', 'UNDO'}
    
    def execute(self, context):
        # Operator logic here
        return {'FINISHED'}

Panels

class BIOXEL_PT_custom_panel(bpy.types.Panel):
    bl_label = "Custom Panel"
    bl_idname = "BIOXEL_PT_custom_panel"
    bl_space_type = 'VIEW_3D'
    bl_region_type = 'UI'
    bl_category = "Bioxel"
    
    def draw(self, context):
        layout = self.layout
        # UI drawing code here

Error Handling

Error Handling Patterns

• Use try-catch blocks for file operations
• Handle user cancellation gracefully
• Report progress for long operations using bioxel_progress_factor and bioxel_progress_text
• Log warnings with print statements for debugging

Key Dependencies

Core Libraries

• bpy (Blender Python API) - Core integration
• numpy - Array processing
• SimpleITK - Medical image processing
• h5py - HDF5 file handling

Scientific Libraries

• matplotlib - Plotting and visualization
• transforms3d - 3D transformations
• pyometiff - OME-TIFF support
• mrcfile - MRC file format support

Development Workflow

Making Changes

1. Identify the appropriate module (operators, panels, bioxel, etc.)
2. Follow existing naming conventions and patterns
3. Use auto-registration - no manual registration needed
4. Test with Blender's Python console
5. Format code with autopep8 before committing

Adding New Features

1. Create appropriate classes in relevant modules
2. Use proper prefixes (BIOXEL_OT_, BIOXEL_PT_, etc.)
3. Add to auto_load system automatically discovers new classes
4. Update documentation if needed

File Operations

• Use pathlib.Path for path operations
• Check file existence before operations
• Handle permissions and missing files gracefully
• Use appropriate file formats (HDF5 for data, PNG for images)

Blender Integration Notes

Asset Library

• Automatically managed via add_asset_library_if_missing()
• Located at NODE_LIB_DIRPATH
• Uses "PACK" import method
• Name: "O Bioxel"

Progress Reporting

• Use bioxel_progress_factor (0.0 to 1.0) for progress
• Use bioxel_progress_text for status messages
• Update via WindowManager properties

Layer Management

• Layers stored as HDF5 files
• Container objects manage multiple layers
• Use layer.py for layer operations
• Support for various medical image formats

Common Pitfalls

Blender API

• Always check context validity
• Handle different Blender versions (check bpy.app.version)
• Use proper property types for UI
• Register classes in correct order (auto_load handles this)

Performance

• Use NumPy for array operations
• Avoid expensive operations in UI draw calls
• Cache computed values where appropriate
• Use background threads for long operations

File I/O

• Always close file handles
• Use context managers for file operations
• Handle large files in chunks
• Validate file formats before processing