### Install Blockpedia Locally

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Command to install the package locally using cargo.

```bash
cargo install --path .
```

--------------------------------

### Install Blockpedia from Source

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Commands to clone the repository and build the project from source.

```bash
git clone https://github.com/Nano112/blockpedia.git
cd blockpedia
cargo build --release
```

--------------------------------

### Basic Library Usage

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Examples for retrieving block data, searching by properties, and accessing color information.

```rust
use blockpedia::{get_block, BLOCKS, queries::*};

// Get a specific block
let stone = get_block("minecraft:stone").unwrap();
println!("Stone properties: {:?}", stone.properties());

// Search for blocks
let redstone_blocks: Vec<_> = find_blocks_by_property("powered", "true").collect();
println!("Found {} powered blocks", redstone_blocks.len());

// Color analysis
if let Some(color) = stone.extras.color {
    println!("Stone color: #{:02X}{:02X}{:02X}", 
        color.rgb[0], color.rgb[1], color.rgb[2]);
}
```

--------------------------------

### Launch Interactive CLI

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Command to start the interactive CLI application.

```bash
cargo run --bin blockpedia-cli
```

--------------------------------

### Generate Color Palettes

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Examples for creating gradients, generating themed palettes, and exporting to various formats.

```rust
use blockpedia::color::palettes::{PaletteGenerator, GradientMethod};
use blockpedia::color::ExtendedColorData;

// Create a gradient between two colors
let red = ExtendedColorData::from_rgb(255, 0, 0);
let blue = ExtendedColorData::from_rgb(0, 0, 255);

let gradient = PaletteGenerator::generate_gradient_palette(
    red, blue, 10, GradientMethod::LinearOklab
);

// Generate themed palettes
let sunset = PaletteGenerator::generate_sunset_palette(8);
let ocean = PaletteGenerator::generate_ocean_palette(6);

// Export to various formats
let css = PaletteGenerator::export_palette_css(&gradient);
let gpl = PaletteGenerator::export_palette_gpl(&gradient, "My Gradient");
```

--------------------------------

### Get Property Statistics

Source: https://context7.com/nano112/blockpedia/llms.txt

Analyze general statistics about block properties, including the total number of unique properties, the most common property, blocks with no properties, and the average number of properties per block.

```rust
// Property statistics
let stats = get_property_stats();
println!("Unique properties: {}", stats.total_unique_properties);
println!("Most common: {} ({} blocks)",
    stats.most_common_property.0, stats.most_common_property.1);
println!("Blocks with no properties: {}", stats.blocks_with_no_properties);
println!("Average properties per block: {:.2}", stats.average_properties_per_block);
```

--------------------------------

### Get Enhanced Block Families

Source: https://context7.com/nano112/blockpedia/llms.txt

Retrieve enhanced block families for better categorization of blocks using `get_enhanced_block_families`.

```rust
// Get enhanced families with better categorization
let enhanced_families = get_enhanced_block_families();
```

--------------------------------

### Get All Possible Property Values

Source: https://context7.com/nano112/blockpedia/llms.txt

Retrieve all unique values for a given block property using `get_property_values`. This function returns an `Option<Vec<String>>`.

```rust
// Get all possible values for a property
if let Some(facing_values) = get_property_values("facing") {
    println!("Facing values: {:?}", facing_values);
    // Output: ["down", "east", "north", "south", "up", "west"]
}
```

--------------------------------

### Get Advanced Property Statistics

Source: https://context7.com/nano112/blockpedia/llms.txt

Access advanced statistics related to block properties, such as identifying the property with the most diverse set of values.

```rust
// Advanced statistics
let advanced_stats = get_advanced_property_stats();
println!("Most diverse property: {} ({} values)",
    advanced_stats.most_diverse_property.0,
    advanced_stats.most_diverse_property.1);
```

--------------------------------

### Get Block Families

Source: https://context7.com/nano112/blockpedia/llms.txt

Obtain block families, which are groups of blocks identified by common suffix patterns, using `get_block_families`.

```rust
// Get block families (grouped by suffix patterns)
let families = get_block_families();
for (family, blocks) in &families {
    println!("{}: {} blocks", family, blocks.len());
}
```

--------------------------------

### Build CLI in Release Mode

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Builds the blockpedia-cli binary in release mode for optimized performance.

```bash
cargo build --release --bin blockpedia-cli
```

--------------------------------

### Build with Alternative Data Source

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Builds the project using an alternative data source by setting the BLOCKPEDIA_DATA_SOURCE environment variable. This is useful for testing or using specific datasets.

```bash
BLOCKPEDIA_DATA_SOURCE=MCPropertyEncyclopedia cargo build
```

--------------------------------

### Block Queries with Blockpedia

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Demonstrates basic block access, property-based searches, pattern matching, statistical analysis, and block family retrieval using the blockpedia crate.

```rust
use blockpedia::{BLOCKS, queries::*, get_block};

// Basic block access
let dirt = get_block("minecraft:dirt")?;
println!("Block: {}", dirt.id());

// Property-based searches
let stairs: Vec<_> = find_blocks_by_property("shape", "straight").collect();
let waterlogged: Vec<_> = find_blocks_by_property("waterlogged", "true").collect();

// Pattern searches  
let wool_blocks: Vec<_> = search_blocks("*wool").collect();
let stone_variants: Vec<_> = search_blocks("*stone*").collect();

// Statistical analysis
let stats = get_property_stats();
println!("Unique properties: {}", stats.total_unique_properties);
println!("Average properties per block: {:.2}", stats.average_properties_per_block);

// Block families
let families = get_block_families();
for (family, blocks) in families {
    println!(ירת{}: {} blocks", family, blocks.len());
}
```

--------------------------------

### Build Project

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Builds the project in development mode. Use `cargo build --release` for a production build.

```bash
cargo build
```

--------------------------------

### Execute Blockpedia CLI Commands

Source: https://context7.com/nano112/blockpedia/llms.txt

Lists common commands for interacting with the Blockpedia CLI, including data building and texture downloading.

```bash
# Launch the interactive CLI
cargo run --bin blockpedia-cli

# Alternative modern CLI
cargo run --bin modern-cli

# Download texture data for color extraction
cargo run --bin download-textures --features network

# List available data sources
cargo run --bin list-sources

# Find blocks missing color data
cargo run --bin missing-colors

# Build data from sources
cargo run --bin build-data --features build-data
```

--------------------------------

### Querying and Transforming Block Collections

Source: https://context7.com/nano112/blockpedia/llms.txt

Demonstrates various filtering techniques including solid block selection, color similarity searches, property-based filtering, and gradient generation.

```rust
use blockpedia::{AllBlocks, GradientConfig, ColorSpace, EasingFunction, ExtendedColorData};

// Basic filtering - find solid building blocks with color data
let solid_blocks = AllBlocks::new()
    .only_solid()
    .exclude_tile_entities()
    .exclude_falling()
    .exclude_transparent()
    .survival_only()
    .with_color()
    .limit(10)
    .collect();

for block in &solid_blocks {
    if let Some(color) = block.extras.color {
        println!("{} (#{:02X}{:02X}{:02X})",
            block.id(), color.rgb[0], color.rgb[1], color.rgb[2]);
    }
}

// Color similarity search
let stone_gray = ExtendedColorData::from_rgb(125, 125, 125);
let gray_blocks = AllBlocks::new()
    .with_color()
    .similar_to_color(stone_gray, 30.0)  // tolerance in Oklab distance
    .sort_by_color_similarity(stone_gray)
    .limit(20)
    .collect();

// Property-based filtering
let redstone_components = AllBlocks::new()
    .with_property("powered")
    .with_property_value("facing", "north")
    .survival_only()
    .sort_by_name()
    .collect();

// Family-based filtering with pattern matching
let wool_blocks = AllBlocks::new()
    .from_families(&["wool", "concrete"])
    .with_color()
    .sort_by_color_gradient()  // Sort for smooth color transitions
    .collect();

let stone_variants = AllBlocks::new()
    .matching("*stone*")
    .exclude_families(&["redstone"])
    .with_color()
    .sort_by_name()
    .limit(8)
    .collect();

// Generate gradient between two colors
let config = GradientConfig::new(10)
    .with_color_space(ColorSpace::Oklab)
    .with_easing(EasingFunction::EaseInOut);

let red = ExtendedColorData::from_rgb(200, 50, 50);
let blue = ExtendedColorData::from_rgb(50, 50, 200);

let gradient_blocks = AllBlocks::new()
    .with_color()
    .generate_gradient_between_colors(red, blue, config)
    .only_solid()
    .collect();

// Check query results
println!("Found {} blocks", gradient_blocks.len());
println!("Any results: {}", AllBlocks::new().with_property("delay").any());
println!("Count: {}", AllBlocks::new().with_color().count());
```

--------------------------------

### Manipulate and Query Colors with ExtendedColorData

Source: https://context7.com/nano112/blockpedia/llms.txt

Demonstrates creating color data, converting between color spaces, calculating perceptual distances, and querying blocks by color similarity.

```rust
use blockpedia::color::{ExtendedColorData, extract_dominant_color};
use blockpedia::BLOCKS;
use std::path::Path;

// Create color data from RGB values
let color = ExtendedColorData::from_rgb(128, 64, 192);

// Access all color space representations
println!("RGB: {:?}", color.rgb);           // [128, 64, 192]
println!("HSL: {:?}", color.hsl);           // [hue, saturation, lightness]
println!("Oklab: {:?}", color.oklab);       // [L, a, b] perceptually uniform
println!("Lab: {:?}", color.lab);           // CIE L*a*b*
println!("Oklch: {:?}", color.oklch);       // [L, chroma, hue]
println!("Hex: {}", color.hex_string());    // #8040C0
println!("Hex value: {:06X}", color.hex);   // 8040C0

// Calculate color distances
let stone_gray = ExtendedColorData::from_rgb(125, 125, 125);
let oak_brown = ExtendedColorData::from_rgb(162, 130, 78);

// Oklab distance (perceptually uniform - recommended)
let oklab_distance = stone_gray.distance_oklab(&oak_brown);
println!("Oklab distance: {:.2}", oklab_distance);

// RGB distance (simple Euclidean)
let rgb_distance = stone_gray.distance_rgb(&oak_brown);
println!("RGB distance: {:.2}", rgb_distance);

// Extract dominant color from texture image
let texture_color = extract_dominant_color(Path::new("assets/textures/stone.png"))
    .expect("Failed to extract color");
println!("Dominant color: {:?}", texture_color.rgb);

// Find blocks by color similarity
let target = ExtendedColorData::from_rgb(100, 100, 100);
let tolerance = 25.0;

let similar_blocks: Vec<_> = BLOCKS.values()
    .filter(|block| {
        if let Some(color) = block.extras.color {
            color.to_extended().distance_oklab(&target) < tolerance
        } else {
            false
        }
    })
    .collect();

// Use built-in color query helpers
if let Some(closest) = blockpedia::BlockFacts::closest_to_color([128, 128, 128]) {
    println!("Closest to gray: {}", closest.id());
}

let similar = blockpedia::BlockFacts::blocks_in_color_range([100, 100, 100], 50.0);
for block in &similar {
    println!("Similar block: {}", block.id());
}
```

--------------------------------

### Run All Tests

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Executes all tests defined in the project. This is a standard command for verifying code integrity.

```bash
cargo test
```

--------------------------------

### Generate Palettes and Gradients with PaletteGenerator

Source: https://context7.com/nano112/blockpedia/llms.txt

Demonstrates creating gradients, themed palettes, and exporting color data to various formats using the PaletteGenerator API.

```rust
use blockpedia::color::palettes::{PaletteGenerator, GradientMethod, ColorGradient};
use blockpedia::color::ExtendedColorData;

// Create a gradient between two colors
let red = ExtendedColorData::from_rgb(255, 0, 0);
let blue = ExtendedColorData::from_rgb(0, 0, 255);

// Different gradient interpolation methods
let rgb_gradient = PaletteGenerator::generate_gradient_palette(
    red, blue, 10, GradientMethod::LinearRgb
);

let hsl_gradient = PaletteGenerator::generate_gradient_palette(
    red, blue, 10, GradientMethod::LinearHsl  // Smooth hue transitions
);

let oklab_gradient = PaletteGenerator::generate_gradient_palette(
    red, blue, 10, GradientMethod::LinearOklab  // Perceptually uniform
);

let bezier_gradient = PaletteGenerator::generate_gradient_palette(
    red, blue, 10, GradientMethod::CubicBezier  // Smooth acceleration
);

// Multi-color gradients
let rainbow_colors = vec![
    ExtendedColorData::from_rgb(255, 0, 0),    // Red
    ExtendedColorData::from_rgb(255, 255, 0),  // Yellow
    ExtendedColorData::from_rgb(0, 255, 0),    // Green
    ExtendedColorData::from_rgb(0, 255, 255),  // Cyan
    ExtendedColorData::from_rgb(0, 0, 255),    // Blue
];

let rainbow = PaletteGenerator::generate_multi_gradient_palette(
    rainbow_colors, 20, GradientMethod::LinearHsl
);

// Pre-designed themed palettes
let sunset = PaletteGenerator::generate_sunset_palette(8);   // Reds to deep blues
let ocean = PaletteGenerator::generate_ocean_palette(6);     // Light to deep blues
let forest = PaletteGenerator::generate_forest_palette(7);   // Light to dark greens
let fire = PaletteGenerator::generate_fire_palette(5);       // Yellow to dark red

// Monochrome palette from a base color
let base = ExtendedColorData::from_rgb(128, 64, 192);
let monochrome = PaletteGenerator::generate_monochrome_palette(base, 9);

// Complementary color palette
let complementary = PaletteGenerator::generate_complementary_palette(&base);

// Generate distinct colors from a set
let colors: Vec<ExtendedColorData> = vec![/* many colors */];
let distinct = PaletteGenerator::generate_distinct_palette(&colors, 8);

// Sort palettes by hue or lightness
let hue_sorted = PaletteGenerator::generate_hue_sorted_palette(&colors);
let lightness_sorted = PaletteGenerator::generate_lightness_sorted_palette(&colors);

// Export formats
let css = PaletteGenerator::export_palette_css(&sunset);
// Output:
// :root {
//   --color-1: #FF5E4D;
//   --color-2: #FF9A00;
//   ...
// }

let gpl = PaletteGenerator::export_palette_gpl(&sunset, "Sunset Gradient");
// GIMP Palette format

let aco_data = PaletteGenerator::export_palette_aco_data(&sunset);
std::fs::write("palette.aco", aco_data).unwrap();
// Adobe Photoshop format

// Using ColorGradient directly for more control
let gradient = ColorGradient::new_two_color(red, blue, 10, GradientMethod::LinearOklab);
let colors = gradient.generate();

let multi_gradient = ColorGradient::new_multi_color(
    rainbow_colors, 20, GradientMethod::LinearHsl
);
let rainbow_palette = multi_gradient.generate();
```

--------------------------------

### Build Skipping Texture Downloads

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Builds the project while skipping texture downloads by setting the BLOCKPEDIA_SKIP_TEXTURES environment variable. This is useful for CI environments or when bandwidth is limited.

```bash
BLOCKPEDIA_SKIP_TEXTURES=1 cargo build
```

--------------------------------

### Handle Errors and Validate Inputs in Rust

Source: https://context7.com/nano112/blockpedia/llms.txt

Demonstrates structured error handling, input validation, and recovery suggestions for block states and properties.

```rust
use blockpedia::{BlockState, BlockpediaError, Result};
use blockpedia::errors::{validation, recovery};
use blockpedia::queries::validated;

// Structured error types
fn handle_errors() -> Result<()> {
    // Block not found error
    let result = BlockState::new("minecraft:nonexistent");
    match result {
        Err(BlockpediaError::Block(e)) => println!("Block error: {}", e),
        _ => {}
    }

    // Property validation error
    let result = BlockState::new("minecraft:repeater")?.with("delay", "5");
    match result {
        Err(BlockpediaError::Property(e)) => println!("Property error: {}", e),
        // "Invalid value '5' for property 'delay'. Valid values: [\"1\", \"2\", \"3\", \"4\"]"
        _ => {}
    }

    Ok(())
}

// Input validation
match validation::validate_block_id("invalid!block:name") {
    Err(e) => println!("Invalid block ID: {}", e),
    Ok(_) => {}
}

match validation::validate_property_name("invalid-prop!") {
    Err(e) => println!("Invalid property name: {}", e),
    Ok(_) => {}
}

match validation::validate_property_value("value with spaces") {
    Err(e) => println!("Invalid property value: {}", e),
    Ok(_) => {}
}

// Error recovery suggestions
let suggestions = recovery::suggest_similar_blocks("stone");
println!("Did you mean: {:?}", suggestions); // ["minecraft:stone"]

let value_suggestions = recovery::suggest_property_values(
    "delay", "5", &["1".to_string(), "2".to_string(), "3".to_string(), "4".to_string()]
);
println!("Valid values: {:?}", value_suggestions);

// Fix common parsing errors
let fixed = recovery::fix_common_parse_errors("minecraft::stone");
println!("Fixed: {}", fixed); // "minecraft:stone"

// Safe query functions with validation
match validated::find_blocks_by_property_safe("nonexistent_prop", "value") {
    Err(e) => println!("Query error: {}", e),
    Ok(blocks) => println!("Found {} blocks", blocks.len()),
}

match validated::search_blocks_safe("*wool") {
    Ok(blocks) => println!("Found {} wool blocks", blocks.len()),
    Err(e) => println!("Search failed: {}", e),
}

// Comprehensive validation before creating state
let properties = vec![
    ("delay".to_string(), "3".to_string()),
    ("facing".to_string(), "north".to_string()),
];

match validated::create_block_state_safe("minecraft:repeater", &properties) {
    Ok(state) => println!("Valid state: {}", state),
    Err(e) => println!("Validation failed: {}", e),
}
```

--------------------------------

### Development Workflow Commands

Source: https://github.com/nano112/blockpedia/blob/main/README.md

A sequence of commands for the typical development workflow, including formatting and linting. Ensure all tests pass before committing.

```bash
git checkout -b feature/amazing-feature
```

```bash
cargo test
```

```bash
cargo fmt
```

```bash
cargo clippy
```

```bash
git commit -m 'Add amazing feature'
```

```bash
git push origin feature/amazing-feature
```

--------------------------------

### Export Palette to GIMP (.gpl) Format

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Exports a color palette into the GIMP Palette (.gpl) file format, including a specified name for the palette.

```rust
// GIMP Palette (.gpl)
let gpl = PaletteGenerator::export_palette_gpl(&palette, "Sunset Gradient");
```

--------------------------------

### Test with Different Data Sources

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Runs tests using a specific data source by setting the BLOCKPEDIA_DATA_SOURCE environment variable. This ensures compatibility with different data configurations.

```bash
BLOCKPEDIA_DATA_SOURCE=MCPropertyEncyclopedia cargo test
```

--------------------------------

### Run Specific Test Suites

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Runs specific test suites by providing their names or keywords. This allows for targeted testing of different functionalities.

```bash
cargo test --test gradient_palettes_test
```

```bash
cargo test color
```

```bash
cargo test queries
```

--------------------------------

### Export Palette to Text

Source: https://github.com/nano112/blockpedia/blob/main/docs/BLOCK_PALETTE_EXAMPLES.md

Converts a generated palette into a formatted text list.

```rust
if let Some(palette) = BlockPaletteGenerator::generate_natural_palette("forest") {
    let text_export = palette.to_text_list();
    println!("{}", text_export);
}
```

--------------------------------

### Clone Blockpedia Repository

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Clones the Blockpedia project repository from GitHub and navigates into the project directory. This is the first step for building from source.

```bash
# Clone the repository
git clone https://github.com/Nano112/blockpedia.git
cd blockpedia
```

--------------------------------

### Generate Modern Architectural Palette

Source: https://github.com/nano112/blockpedia/blob/main/docs/BLOCK_PALETTE_EXAMPLES.md

Use this to generate a palette for modern architectural styles. It typically uses clean blocks like concrete and glass.

```rust
if let Some(modern_palette) = BlockPaletteGenerator::generate_architectural_palette("modern") {
    // Primary: white_concrete (clean surfaces)
    // Secondary: light_gray_concrete (supporting elements)
    // Accent: glass (transparency and light)
}
```

--------------------------------

### Generate Linear Oklab Gradient Palette

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Generates a color palette with perceptually uniform interpolation in the Oklab color space. This results in the most natural-looking gradients to the human eye.

```rust
use blockpedia::color::palettes::{GradientMethod, PaletteGenerator};

// Linear Oklab - Perceptually uniform (most natural to human eye)
let oklab_gradient = PaletteGenerator::generate_gradient_palette(
    start_color, end_color, 10, GradientMethod::LinearOklab
);
```

--------------------------------

### Generate Multi-Color Gradient Palette

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Generates a gradient palette from a list of multiple specified colors using a chosen gradient method, such as Linear Oklab for natural transitions.

```rust
let colors = vec![
    ExtendedColorData::from_rgb(255, 0, 0),   // Red
    ExtendedColorData::from_rgb(255, 255, 0), // Yellow  
    ExtendedColorData::from_rgb(0, 255, 0),   // Green
    ExtendedColorData::from_rgb(0, 0, 255),   // Blue
];

let rainbow = PaletteGenerator::generate_multi_gradient_palette(
    colors, 20, GradientMethod::LinearOklab
);
```

--------------------------------

### Generate Architectural Style Palettes

Source: https://github.com/nano112/blockpedia/blob/main/docs/BLOCK_PALETTE_EXAMPLES.md

Generate palettes for specific building styles using the generate_architectural_palette method.

```rust
if let Some(medieval_palette) = BlockPaletteGenerator::generate_architectural_palette("medieval") {
    // Primary: cobblestone (foundations, walls)
    // Secondary: oak_planks (floors, frames)
    // Accent: stone_bricks (decorative elements)
}
```

--------------------------------

### Convert Between Java and Bedrock Edition States

Source: https://context7.com/nano112/blockpedia/llms.txt

Perform conversions between Java and Bedrock block states and access underlying Bedrock metadata.

```rust
use blockpedia::BlockState;
use std::collections::HashMap;

// Convert Java blockstate to Bedrock
let java_state = BlockState::parse("minecraft:repeater[delay=2,facing=north]").unwrap();
let bedrock_state = java_state.to_bedrock().unwrap();
println!("Bedrock: {}", bedrock_state);

// Convert Bedrock blockstate to Java
let mut bedrock_props = HashMap::new();
bedrock_props.insert("minecraft:cardinal_direction".to_string(), "north".to_string());

let java_from_bedrock = BlockState::from_bedrock("minecraft:repeater", bedrock_props).unwrap();
println!("Java from Bedrock: {}", java_from_bedrock);

// Access Bedrock data from block facts
use blockpedia::BLOCKS;

let block = BLOCKS.get("minecraft:stone").unwrap();
if let Some(bedrock) = block.extras.bedrock {
    println!("Bedrock ID: {}", bedrock.id);
    println!("Bedrock properties: {:?}", bedrock.properties);
    println!("Bedrock default state: {:?}", bedrock.default_state);
}
```

--------------------------------

### Block Transformations with Blockpedia

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Illustrates block state manipulation, including rotation, changing materials, altering shapes, and discovering available variants for blocks using the blockpedia library.

```rust
use blockpedia::{BlockState, transforms::{Direction, BlockShape}};

// Rotation operations
let repeater = BlockState::parse("minecraft:repeater[facing=north,delay=2]")?;
let rotated = repeater.rotate_clockwise()?;
let rotated_180 = repeater.rotate_180()?;
let rotated_ccw = repeater.rotate_counter_clockwise()?;

// Material variants - preserve shape and properties
let oak_stairs = BlockState::parse("minecraft:oak_stairs[facing=north,half=top]")?;
let stone_stairs = oak_stairs.with_material("stone")?;

// Shape variants - preserve material and compatible properties  
let stone_block = BlockState::new("minecraft:stone")?;
let stone_stairs = stone_block.with_shape(BlockShape::Stairs)?;
let stone_slab = stone_block.with_shape(BlockShape::Slab)?;

// Discover available variants
let oak_stairs = BlockState::new("minecraft:oak_stairs")?;
let materials = oak_stairs.available_materials()?;
let shapes = oak_stairs.available_shapes()?;

// Complex transformations
let complex_stairs = BlockState::parse("minecraft:oak_stairs[facing=west,half=top,shape=inner_left]")?;
let rotated_stone = complex_stairs
    .rotate_clockwise()?           // facing=north, shape=inner_right
    .with_material("stone_brick")?;

// Axis rotation for logs and pillars
let log = BlockState::parse("minecraft:oak_log[axis=x]")?;
let rotated_log = log.rotate_clockwise()?;
```

--------------------------------

### Generate Wood Tone Gradient

Source: https://github.com/nano112/blockpedia/blob/main/docs/BLOCK_PALETTE_EXAMPLES.md

Generates a gradient between two wood block types to create depth and realistic shading effects. Requires block references and the number of steps.

```rust
// Light to dark wood for depth effects
let oak_block = BLOCKS.get("minecraft:oak_planks").unwrap();
let dark_oak_block = BLOCKS.get("minecraft:dark_oak_planks").unwrap();

if let Some(wood_gradient) = BlockPaletteGenerator::generate_block_gradient(oak_block, dark_oak_block, 5) {
    // Creates wood tone progression for realistic shading
}
```

--------------------------------

### Create District-Specific Palettes

Source: https://github.com/nano112/blockpedia/blob/main/docs/BLOCK_PALETTE_EXAMPLES.md

Generates architectural color palettes for different districts (e.g., rustic, modern, industrial). This is useful for large-scale city planning to define distinct visual styles for various zones.

```rust
// Create district-specific palettes
let residential = BlockPaletteGenerator::generate_architectural_palette("rustic");
let commercial = BlockPaletteGenerator::generate_architectural_palette("modern");
let industrial = BlockPaletteGenerator::generate_architectural_palette("industrial");

// Use gradients for transition zones
if let (Some(res), Some(com)) = (residential, commercial) {
    // Create gradient between residential and commercial areas
}
```

--------------------------------

### Generate Cubic Bezier Gradient Palette

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Generates a color palette using Cubic Bezier curves for interpolation, allowing for smooth acceleration and deceleration effects in color transitions.

```rust
use blockpedia::color::palettes::{GradientMethod, PaletteGenerator};

// Cubic Bezier - Smooth curves with acceleration/deceleration
let bezier_gradient = PaletteGenerator::generate_gradient_palette(
    start_color, end_color, 10, GradientMethod::CubicBezier
);
```

--------------------------------

### Generate Rustic Architectural Palette

Source: https://github.com/nano112/blockpedia/blob/main/docs/BLOCK_PALETTE_EXAMPLES.md

Use this to generate a palette for rustic architectural styles. It emphasizes natural materials like wood logs and cobblestone.

```rust
if let Some(rustic_palette) = BlockPaletteGenerator::generate_architectural_palette("rustic") {
    // Primary: stripped_oak_log (natural wood)
    // Secondary: cobblestone (sturdy foundations)
    // Accent: hay_bale (agricultural elements)
}
```

--------------------------------

### Color Operations with Blockpedia

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Shows how to extract dominant colors from textures, perform color space conversions (RGB, HSL, Oklab), and find blocks with similar colors using the blockpedia library.

```rust
use blockpedia::color::*;
use std::path::Path;

// Extract colors from textures
let color = extract_dominant_color(Path::new("assets/textures/stone.png"))?;
println!("Dominant color: {:?}", color.rgb);

// Color space conversions
let extended = ExtendedColorData::from_rgb(128, 64, 192);
println!("HSL: {:?}", extended.hsl);
println!("Oklab: {:?}", extended.oklab);
println!("Hex: {}", extended.hex_string());

// Color similarity
let target = ExtendedColorData::from_rgb(125, 125, 125);
let similar_blocks: Vec<_> = BLOCKS.values()
    .filter(|block| {
        if let Some(color) = block.extras.color {
            color.to_extended().distance_oklab(&target) < 20.0
        } else {
            false
        }
    })
    .collect();
```

--------------------------------

### Generate Themed Palettes

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Generates pre-designed palettes for common themes like sunset, ocean, fire, and forest, or dynamic palettes like monochrome and complementary based on a base color.

```rust
// Pre-designed palettes for common use cases
let sunset = PaletteGenerator::generate_sunset_palette(8);      // Warm reds to deep blues
let ocean = PaletteGenerator::generate_ocean_palette(6);        // Light to deep blues  
let fire = PaletteGenerator::generate_fire_palette(5);         // Yellows to deep reds
let forest = PaletteGenerator::generate_forest_palette(7);     // Light to dark greens

// Dynamic palettes based on existing colors
let base_color = ExtendedColorData::from_rgb(128, 64, 192);
let monochrome = PaletteGenerator::generate_monochrome_palette(base_color, 9);
let complementary = PaletteGenerator::generate_complementary_palette(&base_color);
```

--------------------------------

### Generate Stone to Grass Gradient

Source: https://github.com/nano112/blockpedia/blob/main/docs/BLOCK_PALETTE_EXAMPLES.md

Generates a smooth gradient between stone and grass blocks, suitable for natural terrain transitions. Requires block references and the number of steps.

```rust
// Stone to grass transition for natural terrain
let stone_block = BLOCKS.get("minecraft:stone").unwrap();
let grass_block = BLOCKS.get("minecraft:grass_block").unwrap();

if let Some(gradient) = BlockPaletteGenerator::generate_block_gradient(stone_block, grass_block, 7) {
    // Creates smooth transition: stone → cobblestone → dirt variants → grass
}
```

--------------------------------

### Building and Parsing BlockStates

Source: https://context7.com/nano112/blockpedia/llms.txt

Create, manipulate, and parse Minecraft block states with built-in property validation.

```rust
use blockpedia::{BlockState, BlockFacts, BLOCKS};

// Create a simple block state
let stone_state = BlockState::new("minecraft:stone").unwrap();
println!("Simple state: {}", stone_state);

// Build a complex block state with properties using fluent API
let repeater_state = BlockState::new("minecraft:repeater")
    .unwrap()
    .with("delay", "3")
    .unwrap()
    .with("facing", "north")
    .unwrap()
    .with("powered", "false")
    .unwrap();
println!("Complex state: {}", repeater_state);
// Output: minecraft:repeater[delay=3,facing=north,powered=false]

// Parse an existing blockstate string
let parsed = BlockState::parse("minecraft:oak_stairs[facing=west,half=top,shape=inner_left]").unwrap();
println!("Parsed state: {}", parsed);
println!("Facing: {:?}", parsed.get_property("facing"));

// Create from default state
let repeater_facts = BLOCKS.get("minecraft:repeater").unwrap();
let default_state = BlockState::from_default(repeater_facts).unwrap();
println!("Default repeater: {}", default_state);

// Validation catches invalid blocks and properties
match BlockState::new("minecraft:nonexistent") {
    Err(e) => println!("Error: {}", e), // Block 'minecraft:nonexistent' not found
    Ok(_) => {}
}

match BlockState::new("minecraft:repeater").unwrap().with("delay", "5") {
    Err(e) => println!("Error: {}", e), // Invalid value '5' for property 'delay'
    Ok(_) => {}
}
```

--------------------------------

### Generate Industrial Architectural Palette

Source: https://github.com/nano112/blockpedia/blob/main/docs/BLOCK_PALETTE_EXAMPLES.md

Use this to generate a palette for industrial architectural styles. It focuses on materials like iron and concrete, often with redstone accents.

```rust
if let Some(industrial_palette) = BlockPaletteGenerator::generate_architectural_palette("industrial") {
    // Primary: iron_block (structural elements)
    // Secondary: gray_concrete (utilitarian surfaces)
    // Accent: redstone_block (functional components)
}
```

--------------------------------

### Generate Palettes for Historical Architecture

Source: https://github.com/nano112/blockpedia/blob/main/docs/BLOCK_PALETTE_EXAMPLES.md

Generates natural and architectural palettes for recreating historical architecture styles like Ancient Egyptian, Roman/Greek, Medieval European, and Industrial Revolution.

```rust
// Ancient Egyptian
let egyptian = BlockPaletteGenerator::generate_natural_palette("desert");

// Roman/Greek
let classical = BlockPaletteGenerator::generate_natural_palette("mountain");

// Medieval European
let medieval = BlockPaletteGenerator::generate_architectural_palette("medieval");

// Industrial Revolution
let industrial = BlockPaletteGenerator::generate_architectural_palette("industrial");
```

--------------------------------

### Generate Custom Palette from Wood Block Colors

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Extracts colors from blocks with 'wood' or 'log' in their IDs, then generates a distinct color palette from these extracted colors using a specified number of colors.

```rust
use blockpedia::{BLOCKS, color::palettes::PaletteGenerator};

// Get colors from wood blocks
let wood_colors: Vec<_> = BLOCKS.values()
    .filter(|block| block.id().contains("wood") || block.id().contains("log"))
    .filter_map(|block| block.extras.color.map(|c| c.to_extended()))
    .collect();

let wood_palette = PaletteGenerator::generate_distinct_palette(&wood_colors, 8);
let css_export = PaletteGenerator::export_palette_css(&wood_palette);
```

--------------------------------

### Extract Color from Image

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Initializes a ColorExtractor with a specified method and extracts a dominant color from an image. Supports different extraction strategies like MostFrequent, Average, Clustering, and EdgeWeighted.

```rust
use blockpedia::color::extraction::{ColorExtractor, ExtractionMethod};

let extractor = ColorExtractor::new(ExtractionMethod::MostFrequent { bins: 16 });
let color = extractor.extract_color(&image)?;

// Different extraction methods
let average = ExtractionMethod::Average;
let clustering = ExtractionMethod::Clustering { k: 5 };
let edge_weighted = ExtractionMethod::EdgeWeighted;
```

--------------------------------

### Search Blocks with Glob-like Patterns

Source: https://context7.com/nano112/blockpedia/llms.txt

Employ `search_blocks` for flexible block searching using glob-like patterns to match block IDs.

```rust
// Search with glob-like patterns
let wool_blocks: Vec<_> = search_blocks("*wool").collect();
let stone_variants: Vec<_> = search_blocks("*stone*").collect();
let oak_items: Vec<_> = search_blocks("minecraft:oak_*").collect();
```

--------------------------------

### Generate Natural Biome Palettes

Source: https://github.com/nano112/blockpedia/blob/main/docs/BLOCK_PALETTE_EXAMPLES.md

Generate palettes tailored to specific Minecraft biomes using the generate_natural_palette method.

```rust
// Generate a forest-themed palette
if let Some(forest_palette) = BlockPaletteGenerator::generate_natural_palette("forest") {
    println!("Forest palette contains {} blocks", forest_palette.blocks.len());
    // Typical blocks: oak_log, oak_leaves, grass_block, coarse_dirt, moss_block
}
```

```rust
// Desert themes work great for Middle Eastern architecture
if let Some(desert_palette) = BlockPaletteGenerator::generate_natural_palette("desert") {
    // Typical blocks: sand, sandstone, smooth_sandstone, cut_sandstone, red_sand, terracotta
}
```

```rust
// Ocean palettes for aquatic builds
if let Some(ocean_palette) = BlockPaletteGenerator::generate_natural_palette("ocean") {
    // Typical blocks: water, prismarine, dark_prismarine, sea_lantern, kelp, sand
}
```

```rust
// Rocky, mineral-rich palettes
if let Some(mountain_palette) = BlockPaletteGenerator::generate_natural_palette("mountain") {
    // Typical blocks: stone, cobblestone, andesite, granite, diorite, gravel
}
```

```rust
// Hellish, otherworldly themes
if let Some(nether_palette) = BlockPaletteGenerator::generate_natural_palette("nether") {
    // Typical blocks: netherrack, nether_bricks, blackstone, crimson_planks, warped_planks
}
```

```rust
// Ethereal, alien environments
if let Some(end_palette) = BlockPaletteGenerator::generate_natural_palette("end") {
    // Typical blocks: end_stone, purpur_block, end_stone_bricks, obsidian, chorus_flower
}
```

--------------------------------

### Generate Complementary Palettes

Source: https://github.com/nano112/blockpedia/blob/main/docs/BLOCK_PALETTE_EXAMPLES.md

Creates high-contrast palettes using opposite colors on the color wheel.

```rust
// High contrast for focal points
let red_block = BLOCKS.get("minecraft:red_wool").unwrap();

if let Some(comp_palette) = BlockPaletteGenerator::generate_complementary_palette(red_block) {
    // Provides: red primary + green complement + supporting colors
}
```

```rust
// Cool-warm balance
let blue_block = BLOCKS.get("minecraft:blue_wool").unwrap();

if let Some(comp_palette) = BlockPaletteGenerator::generate_complementary_palette(blue_block) {
    // Provides: cool blue + warm orange + neutrals
}
```

--------------------------------

### Find Blocks by Property Value

Source: https://context7.com/nano112/blockpedia/llms.txt

Use `find_blocks_by_property` to locate blocks based on a specific property and its value. Requires importing `blockpedia::queries::*` and `blockpedia::BLOCKS`.

```rust
use blockpedia::queries::*
use blockpedia::BLOCKS;

// Find blocks by property value
let powered_blocks: Vec<_> = find_blocks_by_property("powered", "true").collect();
println!("Powered blocks: {}", powered_blocks.len());
```

--------------------------------

### Generate and Export Forest Palette to JSON

Source: https://github.com/nano112/blockpedia/blob/main/docs/BLOCK_PALETTE_EXAMPLES.md

Generates a natural color palette for a forest theme and exports it to JSON format. This is useful for saving and sharing palette configurations.

```rust
if let Some(palette) = BlockPaletteGenerator::generate_natural_palette("forest") {
    let json_export = palette.to_json();
    println!("{}", json_export);
}
```

--------------------------------

### Search Blocks by Color Range

Source: https://github.com/nano112/blockpedia/blob/main/docs/BLOCK_PALETTE_EXAMPLES.md

Finds blocks matching a specific RGB color within a defined tolerance.

```rust
// Find stone-gray alternatives
let target_gray = ExtendedColorData::from_rgb(128, 128, 128);
let gray_blocks = BlockPaletteGenerator::find_blocks_by_color_range(target_gray, 30.0, 10);

// Find warm earth tones
let target_brown = ExtendedColorData::from_rgb(139, 69, 19);
let earth_blocks = BlockPaletteGenerator::find_blocks_by_color_range(target_brown, 40.0, 8);

// Find ocean blues
let target_blue = ExtendedColorData::from_rgb(70, 130, 180);
let ocean_blocks = BlockPaletteGenerator::find_blocks_by_color_range(target_blue, 45.0, 12);
```

--------------------------------

### Accessing Block Data and PHF Tables

Source: https://context7.com/nano112/blockpedia/llms.txt

Retrieve block information by ID, access color data, and perform O(1) lookups using the PHF table.

```rust
use blockpedia::{get_block, all_blocks, BLOCKS};

// Get a specific block by ID
let stone = get_block("minecraft:stone").unwrap();
println!("Block ID: {}", stone.id());
println!("Properties: {:?}", stone.properties());
println!("Is transparent: {}", stone.transparent);

// Access color data if available
if let Some(color) = stone.extras.color {
    println!("RGB: {:?}", color.rgb);
    println!("Oklab: {:?}", color.oklab);
    println!("Hex: #{:02X}{:02X}{:02X}", color.rgb[0], color.rgb[1], color.rgb[2]);
}

// Access the PHF table directly for O(1) lookups
println!("Total blocks loaded: {}", BLOCKS.len());

let repeater = BLOCKS.get("minecraft:repeater").unwrap();
println!("Has delay property: {}", repeater.has_property("delay"));
println!("Delay values: {:?}", repeater.get_property_values("delay"));
println!("Default delay: {:?}", repeater.get_property("delay"));

// Iterate over all blocks
for block in all_blocks() {
    if block.has_property("powered") {
        println!("Redstone component: {}", block.id());
    }
}
```

--------------------------------

### Generate Monochrome Palettes

Source: https://github.com/nano112/blockpedia/blob/main/docs/BLOCK_PALETTE_EXAMPLES.md

Creates a palette of blocks based on a single base block's color variants.

```rust
// Stone-based monochrome for modern minimalism
let stone_block = BLOCKS.get("minecraft:stone").unwrap();

if let Some(gray_mono) = BlockPaletteGenerator::generate_monochrome_palette(stone_block, 6) {
    // Provides: darkest stone → mid grays → lightest stone variants
}
```

```rust
// Oak-based monochrome for cozy builds
let oak_block = BLOCKS.get("minecraft:oak_planks").unwrap();

if let Some(wood_mono) = BlockPaletteGenerator::generate_monochrome_palette(oak_block, 7) {
    // Provides: dark oak variants → natural oak → light wood tones
}
```

```rust
// Red wool monochrome for dramatic effect
let red_block = BLOCKS.get("minecraft:red_wool").unwrap();

if let Some(red_mono) = BlockPaletteGenerator::generate_monochrome_palette(red_block, 5) {
    // Provides: deep burgundy → bright red → pink variants
}
```

--------------------------------

### Generate Linear RGB Gradient Palette

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Generates a color palette by interpolating between two colors using the Linear RGB color space. Useful for simple, direct color transitions.

```rust
use blockpedia::color::palettes::{GradientMethod, PaletteGenerator};

// Linear RGB - Simple RGB interpolation
let rgb_gradient = PaletteGenerator::generate_gradient_palette(
    start_color, end_color, 10, GradientMethod::LinearRgb
);
```

--------------------------------

### Generate Complementary Palettes for Teams

Source: https://github.com/nano112/blockpedia/blob/main/docs/BLOCK_PALETTE_EXAMPLES.md

Generates complementary color palettes based on a base block for different teams. This is useful for team building projects to assign distinct and harmonious color schemes.

```rust
// Assign complementary palettes to different teams
let team_red_base = BLOCKS.get("minecraft:red_wool").unwrap();
let team_blue_base = BLOCKS.get("minecraft:blue_wool").unwrap();

let team_red_palette = BlockPaletteGenerator::generate_complementary_palette(team_red_base);
let team_blue_palette = BlockPaletteGenerator::generate_complementary_palette(team_blue_base);
```

--------------------------------

### Export Palette to CSS Variables

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Exports a generated color palette into a CSS string format, suitable for use as CSS variables.

```rust
// CSS Variables
let css = PaletteGenerator::export_palette_css(&palette);
/*
:root {
  --color-1: #FF0000;
  --color-2: #FF8000;
  --color-3: #FFFF00;
}
*/
```

--------------------------------

### Generate Linear HSL Gradient Palette

Source: https://github.com/nano112/blockpedia/blob/main/README.md

Creates a color palette using interpolation in the Linear HSL color space. This method provides smooth transitions, especially for hue changes.

```rust
use blockpedia::color::palettes::{GradientMethod, PaletteGenerator};

// Linear HSL - Hue-based interpolation (smooth color wheel transitions)
let hsl_gradient = PaletteGenerator::generate_gradient_palette(
    start_color, end_color, 10, GradientMethod::LinearHsl
);
```

--------------------------------

### Perform Block Transformations in Rust

Source: https://context7.com/nano112/blockpedia/llms.txt

Use these methods to rotate blocks, change materials, or modify shapes while preserving existing properties. Requires the blockpedia crate.

```rust
use blockpedia::{BlockState, BlockShape, BlockTransforms, Direction, Rotation};

// Rotation operations
let repeater = BlockState::parse("minecraft:repeater[facing=north,delay=2]").unwrap();

let rotated_cw = repeater.rotate_clockwise().unwrap();       // facing=east
let rotated_180 = repeater.rotate_180().unwrap();            // facing=south
let rotated_ccw = repeater.rotate_counter_clockwise().unwrap(); // facing=west

println!("Original: {}", repeater);      // minecraft:repeater[delay=2,facing=north]
println!("Clockwise: {}", rotated_cw);   // minecraft:repeater[delay=2,facing=east]
println!("180°: {}", rotated_180);       // minecraft:repeater[delay=2,facing=south]
println!("Counter-clockwise: {}", rotated_ccw); // minecraft:repeater[delay=2,facing=west]

// Stair shapes rotate correctly
let stairs = BlockState::parse("minecraft:oak_stairs[facing=west,half=top,shape=inner_left]").unwrap();
let rotated_stairs = stairs.rotate_clockwise().unwrap();
println!("Rotated stairs: {}", rotated_stairs);
// facing=north, shape=inner_right

// Log/pillar axis rotation
let log = BlockState::parse("minecraft:oak_log[axis=x]").unwrap();
let rotated_log = log.rotate_clockwise().unwrap();
println!("Rotated log: {}", rotated_log); // axis=z

// Material variants - preserve shape and properties
let oak_stairs = BlockState::parse("minecraft:oak_stairs[facing=north,half=top]").unwrap();
let stone_stairs = oak_stairs.with_material("stone").unwrap();
println!("Stone stairs: {}", stone_stairs);
// minecraft:stone_stairs[facing=north,half=top]

let stone_brick_stairs = oak_stairs.with_material("stone_brick").unwrap();
println!("Stone brick stairs: {}", stone_brick_stairs);

// Shape variants - preserve material
let stone = BlockState::new("minecraft:stone").unwrap();

let stone_stairs = stone.with_shape(BlockShape::Stairs).unwrap();
println!("Stone stairs: {}", stone_stairs);
// minecraft:stone_stairs[facing=north,half=bottom,shape=straight]

let stone_slab = stone.with_shape(BlockShape::Slab).unwrap();
println!("Stone slab: {}", stone_slab);
// minecraft:stone_slab[type=bottom]

// Discover available variants
let oak_stairs = BlockState::new("minecraft:oak_stairs").unwrap();

let materials = oak_stairs.available_materials().unwrap();
println!("Available materials: {:?}", materials);
// ["acacia", "andesite", "bamboo", "birch", "brick", ...]

let shapes = oak_stairs.available_shapes().unwrap();
println!("Available shapes: {:?}", shapes);
// [Stairs, Slab, Fence, Door, Trapdoor, ...]

// Direction utilities
let north = Direction::North;
let rotated = north.rotate_clockwise(); // East
let opposite = north.opposite();        // South
let rotated_by = north.apply_rotation(Rotation::Half); // South
```