### Install Sphinx for Documentation

Source: https://github.com/smylermc/litemapy/blob/master/docs/source/contributing.md

Commands to install Sphinx and the Read the Docs theme within a virtual environment for building documentation locally.

```bash
python -m pip install Sphinx sphinx-rtd-theme
```

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

### Set up Development Environment

Source: https://github.com/smylermc/litemapy/blob/master/docs/source/contributing.md

Commands to create and activate a Python virtual environment, and install the project in editable mode with pytest.

```bash
python -m venv venv
source venv/bin/activate
python -m pip install -e . 
python -m pip install pytest
```

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

### Install Litemapy via pip

Source: https://github.com/smylermc/litemapy/blob/master/docs/source/setup.md

Use this command to install the library from PyPi.

```sh
python -m pip install litemapy
```

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

### Install Pytest for Testing

Source: https://github.com/smylermc/litemapy/blob/master/docs/source/contributing.md

Command to install pytest within an activated virtual environment for running unit tests.

```bash
python -m pip install pytest
```

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

### Set and Get Blocks in a Region

Source: https://context7.com/smylermc/litemapy/llms.txt

Demonstrates basic block placement, retrieval, and conditional checks within a region, followed by building a hollow cube.

```python
# Set blocks using array indexing
region[0, 0, 0] = stone
region[1, 0, 0] = glass
region[2, 0, 0] = redstone_lamp

# Get blocks
block = region[0, 0, 0]
print(f"Block at origin: {block.id}")  # minecraft:stone

# Check if specific block exists in region
if stone in region:
    print("Stone is used in this region")

# Build a structure - hollow cube of glass
for x in range(16):
    for y in range(16):
        for z in range(16):
            # Only place on edges
            if x in (0, 15) or y in (0, 15) or z in (0, 15):
                region[x, y, z] = glass

schematic.save("hollow_cube.litematic")
```

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

### Set and Get Blocks in a Region

Source: https://context7.com/smylermc/litemapy/llms.txt

Use array-style indexing to get and set blocks at specific coordinates within a region. This allows for direct manipulation of the block data.

```python
from litemapy import Schematic, Region, BlockState

# Create a region
region = Region(0, 0, 0, 16, 16, 16)
schematic = region.as_schematic(name="Block Demo")

# Create block states
stone = BlockState("minecraft:stone")
glass = BlockState("minecraft:glass")
redstone_lamp = BlockState("minecraft:redstone_lamp", lit="true")
```

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

### Work with Region Coordinate Bounds

Source: https://context7.com/smylermc/litemapy/llms.txt

Demonstrates how to get and use local and schematic coordinate bounds for a Region object, including iterating through its coordinate ranges. Regions can have negative dimensions.

```python
from litemapy import Region

# Regions can have negative dimensions
# This creates a region extending in negative direction
region = Region(10, 5, 10, -5, 10, -5)

# Local coordinate bounds (within region's own system)
print(f"Local X range: {region.min_x()} to {region.max_x()}")
print(f"Local Y range: {region.min_y()} to {region.max_y()}")
print(f"Local Z range: {region.min_z()} to {region.max_z()}")

# Schematic coordinate bounds (position in schematic)
print(f"Schematic X range: {region.min_schem_x()} to {region.max_schem_x()}")
print(f"Schematic Y range: {region.min_schem_y()} to {region.max_schem_y()}")
print(f"Schematic Z range: {region.min_schem_z()} to {region.max_schem_z()}")

# Use ranges for iteration
for x in region.range_x():
    for y in region.range_y():
        for z in region.range_z():
            # x, y, z are in local coordinates
            pass
```

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

### Accessing Blocks in Regions

Source: https://github.com/smylermc/litemapy/blob/master/CHANGELOG.md

Use bracket notation to get or set blocks within a region.

```python
block = region[x, y, z]
```

```python
region[x, y, z] = block
```

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

### Load Minecraft Structure File

Source: https://context7.com/smylermc/litemapy/llms.txt

Loads a Minecraft structure file (NBT format) and extracts region data. Ensure the 'nbtlib' and 'litemapy' libraries are installed.

```python
import nbtlib
from litemapy import Region

# Load a Minecraft structure file
structure_file = nbtlib.File.load("pyramid.nbt", gzipped=True)
region, mc_version = Region.from_structure_nbt(structure_file)
print(f"Structure size: {region.width}x{region.height}x{region.length}")
```

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

### Build Documentation Locally

Source: https://github.com/smylermc/litemapy/blob/master/docs/source/contributing.md

Commands to navigate to the docs directory and build the HTML documentation using Sphinx.

```bash
cd docs
make html
```

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

### Creating Multi-Region Schematics

Source: https://context7.com/smylermc/litemapy/llms.txt

Illustrates how to initialize a schematic with multiple named regions and populate them with different block states.

```python
from litemapy import Schematic, Region, BlockState

# Create schematic with multiple regions
schematic = Schematic(
    name="Multi-Room House",
    author="Architect",
    description="A house with multiple rooms"
)

# Create regions at different positions
living_room = Region(0, 0, 0, 10, 5, 10)
bedroom = Region(10, 0, 0, 8, 5, 8)
kitchen = Region(0, 0, 10, 6, 5, 6)

# Add regions to schematic
schematic.regions["Living Room"] = living_room
schematic.regions["Bedroom"] = bedroom
schematic.regions["Kitchen"] = kitchen

# Fill each room with different flooring
oak_planks = BlockState("minecraft:oak_planks")
carpet = BlockState("minecraft:white_carpet")
stone = BlockState("minecraft:stone")

for x in range(10):
    for z in range(10):
        living_room[x, 0, z] = oak_planks

for x in range(8):
    for z in range(8):
        bedroom[x, 0, z] = carpet

for x in range(6):
    for z in range(6):
        kitchen[x, 0, z] = stone

# Check schematic dimensions (computed from all regions)
print(f"Total width: {schematic.width}")
print(f"Total height: {schematic.height}")
print(f"Total length: {schematic.length}")

schematic.save("house.litematic")
```

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

### Create and Manage Entities

Source: https://context7.com/smylermc/litemapy/llms.txt

Demonstrates creating an armor stand entity, adding custom NBT tags, and appending it to a region.

```python
armor_stand = Entity("minecraft:armor_stand")
armor_stand.position = (5.0, 1.0, 5.0)
armor_stand.rotation = (45.0, 0.0)  # Yaw, Pitch
armor_stand.motion = (0.0, 0.0, 0.0)

# Add custom NBT data
armor_stand.add_tag("CustomName", String('{"text":"Guard"}'))
armor_stand.add_tag("ShowArms", Byte(1))
armor_stand.add_tag("NoGravity", Byte(1))

# Add entity to region
region.entities.append(armor_stand)

# Load schematic and access entities
schematic.save("with_entities.litematic")
loaded = Schematic.load("with_entities.litematic")

for region in loaded.regions.values():
    for entity in region.entities:
        print(f"Entity: {entity.id}")
        print(f"  Position: {entity.position}")
        print(f"  Rotation: {entity.rotation}")
```

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

### Instantiate and Access BlockState Properties

Source: https://github.com/smylermc/litemapy/blob/master/docs/source/blocks.md

Demonstrates creating a BlockState instance with a block identifier and a property, and accessing its ID and properties.

```python
>>> block = BlockState("minecraft:oak_log", facing="up")
>>> block.id
"minecraft:oak_log"
>>> block["facing"]
"up"
>>> "facing" in block
True
```

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

### Working with Tile Entities

Source: https://context7.com/smylermc/litemapy/llms.txt

Shows how to define a tile entity with custom NBT data for a chest and attach it to a region.

```python
from litemapy import Schematic, Region, BlockState, TileEntity
from nbtlib.tag import Compound, String, List, Byte

# Create region
region = Region(0, 0, 0, 5, 5, 5)
schematic = region.as_schematic(name="Chest Room")

# Place a chest block
chest = BlockState("minecraft:chest", facing="north")
region[2, 0, 2] = chest

# Create tile entity with chest contents
chest_data = Compound({
    "id": String("minecraft:chest"),
    "x": 2, "y": 0, "z": 2,
    "Items": List[Compound]([
        Compound({
            "Slot": Byte(0),
            "id": String("minecraft:diamond"),
            "Count": Byte(64)
        }),
        Compound({
            "Slot": Byte(1),
            "id": String("minecraft:gold_ingot"),
            "Count": Byte(32)
        })
    ])
})
tile_entity = TileEntity(chest_data)
region.tile_entities.append(tile_entity)

# Save and load
schematic.save("chest_room.litematic")
loaded = Schematic.load("chest_room.litematic")

for region in loaded.regions.values():
    for tile_entity in region.tile_entities:
        print(f"Tile entity at: {tile_entity.position}")
```

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

### Create and Manipulate Schematics

Source: https://github.com/smylermc/litemapy/blob/master/docs/source/setup.md

Demonstrates creating a new schematic, populating a region with block states, saving to a file, and reading back the data.

```python
from litemapy import Schematic, Region, BlockState

# Shortcut to create a schematic with a single region
reg = Region(0, 0, 0, 21, 21, 21)
schem = reg.as_schematic(name="Planet", author="SmylerMC", description="Made with litemapy")

# Create the block state we are going to use
block = BlockState("minecraft:light_blue_concrete")

# Build the planet
for x, y, z in reg.block_positions():
    if round(((x-10)**2 + (y-10)**2 + (z-10)**2)**.5) <= 10:
        reg[x, y, z] = block

# Save the schematic
schem.save("planet.litematic")

# Load the schematic and get its first region
schem = Schematic.load("planet.litematic")
reg = list(schem.regions.values())[0]

# Print out the basic shape
for x in reg.range_x():
    for z in reg.range_z():
        b = reg[x, 10, z]
        if b.id == "minecraft:air":
            print(" ", end="")
        else:
            print("#", end='')
    print()
```

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

### BlockState Class Initialization

Source: https://github.com/smylermc/litemapy/blob/master/docs/source/blocks.md

Describes how to instantiate and access properties of a BlockState object.

```APIDOC
## BlockState Class

### Description
Represents a block in a schematic, containing a block identifier and a set of block properties.

### Initialization
`BlockState(id: str, **properties)`

- **id** (str) - The block identifier (e.g., "minecraft:oak_log").
- **properties** (dict) - Key-value pairs representing block states (e.g., facing="up").

### Usage Example
```python
block = BlockState("minecraft:oak_log", facing="up")
print(block.id) # "minecraft:oak_log"
print(block["facing"]) # "up"
print("facing" in block) # True
```
```

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

### Converting to Minecraft Structure Format

Source: https://context7.com/smylermc/litemapy/llms.txt

Demonstrates exporting a region to the native Minecraft structure NBT format.

```python
from litemapy import Schematic, Region, BlockState
import nbtlib

# Create a region
region = Region(0, 0, 0, 10, 10, 10)
glass = BlockState("minecraft:glass")

# Build a glass pyramid
for y in range(5):
    for x in range(y, 10-y):
        for z in range(y, 10-y):
            region[x, y, z] = glass

# Convert to Minecraft structure format
structure_nbt = region.to_structure_nbt(
    mc_version=2975,    # Minecraft data version
    gzipped=True,
    byteorder='big'
)

# Save as .nbt structure file
structure_nbt.save("pyramid.nbt")
```

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

### Working with Entities

Source: https://context7.com/smylermc/litemapy/llms.txt

Initializes a region and schematic for entity manipulation.

```python
from litemapy import Schematic, Region, Entity
from nbtlib.tag import String, Byte

# Create region and schematic
region = Region(0, 0, 0, 10, 10, 10)
schematic = region.as_schematic(name="Entity Demo")
```

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

### Load Schematic from File

Source: https://context7.com/smylermc/litemapy/llms.txt

Load an existing .litematic file and access its metadata and regions. Schematics can contain multiple regions.

```python
from litemapy import Schematic

# Load an existing schematic
schematic = Schematic.load("my_build.litematic")

# Access metadata
print(f"Name: {schematic.name}")
print(f"Author: {schematic.author}")
print(f"Description: {schematic.description}")
print(f"Dimensions: {schematic.width}x{schematic.height}x{schematic.length}")

# Access regions (schematics can have multiple regions)
for region_name, region in schematic.regions.items():
    print(f"Region '{region_name}':")
    print(f"  Position: ({region.x}, {region.y}, {region.z})")
    print(f"  Size: {region.width}x{region.height}x{region.length}")
    print(f"  Volume: {region.volume()} blocks")
    print(f"  Non-air blocks: {region.count_blocks()}")
```

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

### Constructing Block States

Source: https://github.com/smylermc/litemapy/blob/master/CHANGELOG.md

Create a new BlockState by providing properties as keyword arguments.

```python
BlockState("minecraft:acacia_log", facing="west")
```

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

### Run Project Tests

Source: https://github.com/smylermc/litemapy/blob/master/docs/source/contributing.md

Command to execute all project tests using pytest from the root directory.

```bash
python -m pytest
```

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

### Save Schematic to File

Source: https://context7.com/smylermc/litemapy/llms.txt

Save a schematic to a .litematic file. Options include updating metadata, adding a software identifier, and gzip compression.

```python
from litemapy import Schematic, Region, BlockState

# Create schematic
region = Region(0, 0, 0, 10, 10, 10)
schematic = region.as_schematic(name="Tower", author="Builder")

# Place some blocks
stone = BlockState("minecraft:stone")
for x in range(10):
    for z in range(10):
        region[x, 0, z] = stone

# Save to file
schematic.save("tower.litematic")

# Save with options
schematic.save(
    "tower.litematic",
    update_meta=True,   # Update modification timestamp
    save_soft=True,     # Add software identifier
    gzipped=True        # Compress with gzip (default)
)
```

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

### Converting to Sponge Schematic Format

Source: https://context7.com/smylermc/litemapy/llms.txt

Provides methods for exporting regions to the Sponge format and importing them back into litemapy.

```python
from litemapy import Schematic, Region, BlockState

# Create or load a region
region = Region(0, 0, 0, 16, 16, 16)
stone = BlockState("minecraft:stone")
for x, y, z in region.block_positions():
    if y == 0:
        region[x, y, z] = stone

# Convert to Sponge format NBT file
sponge_nbt = region.to_sponge_nbt(
    mc_version=2975,    # Minecraft 1.18.2 data version
    gzipped=True,       # Compress (required by WorldEdit)
    endianness='big'    # Big endian (required by WorldEdit)
)

# Save as .schem file
sponge_nbt.save("build.schem")

# Load a Sponge schematic and convert to Litemapy region
import nbtlib
sponge_file = nbtlib.File.load("build.schem", gzipped=True)
region, mc_version = Region.from_sponge_nbt(sponge_file)
print(f"Loaded region, MC version: {mc_version}")
```

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

### Create Schematic with Single Region

Source: https://context7.com/smylermc/litemapy/llms.txt

Create a schematic containing a single region with metadata. The region is defined by its position and dimensions.

```python
from litemapy import Schematic, Region, BlockState

# Create a region at position (0,0,0) with dimensions 21x21x21
region = Region(0, 0, 0, 21, 21, 21)

# Convert to schematic with metadata
schematic = region.as_schematic(
    name="My Structure",
    author="Builder",
    description="A sample structure made with litemapy"
)

# Access schematic properties
print(f"Schematic name: {schematic.name}")
print(f"Dimensions: {schematic.width}x{schematic.height}x{schematic.length}")
```

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

### Access Region Palette

Source: https://context7.com/smylermc/litemapy/llms.txt

Loads a schematic and iterates through its regions to access and print the palette of unique block states for each region. Air is always at index 0.

```python
from litemapy import Schematic

# Load a schematic
schematic = Schematic.load("build.litematic")

for region_name, region in schematic.regions.items():
    print(f"Region: {region_name}")

    # Get the palette (tuple of unique BlockStates)
    palette = region.palette
    print(f"  Unique block types: {len(palette)}")

    for block_state in palette:
        print(f"    {block_state}")
        # BlockState string representation shows id and properties
        # e.g., minecraft:oak_stairs[facing=north,half=bottom]
```

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

### NBT Serialization and Deserialization

Source: https://context7.com/smylermc/litemapy/llms.txt

Shows how to convert Litemapy Schematics and Regions to and from NBT compound tags for custom processing or integration with other tools. Supports saving soft NBT data.

```python
from litemapy import Schematic, Region, BlockState
import nbtlib

# Create a schematic
region = Region(0, 0, 0, 5, 5, 5)
stone = BlockState("minecraft:stone")
region[0, 0, 0] = stone
schematic = region.as_schematic(name="NBT Demo")

# Convert to NBT compound
nbt_data = schematic.to_nbt(save_soft=True)

# Access raw NBT data
print(f"Version: {nbt_data['Version']}")
print(f"Metadata name: {nbt_data['Metadata']['Name']}")

# Create schematic from NBT
restored = Schematic.from_nbt(nbt_data)
print(f"Restored name: {restored.name}")

# Similarly for regions
region_nbt = region.to_nbt()
restored_region = Region.from_nbt(region_nbt)
```

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

### Create and Use BlockState Objects

Source: https://context7.com/smylermc/litemapy/llms.txt

Represent Minecraft blocks with their IDs and properties. Block states are immutable; use `with_properties()` or `with_id()` to create modified copies.

```python
from litemapy import BlockState

# Simple block without properties
stone = BlockState("minecraft:stone")
print(stone.id)  # minecraft:stone

# Block with properties
oak_stairs = BlockState(
    "minecraft:oak_stairs",
    facing="north",
    half="bottom",
    shape="straight",
    waterlogged="false"
)
print(oak_stairs.id)           # minecraft:oak_stairs
print(oak_stairs["facing"])    # north
print("facing" in oak_stairs)  # True

# Iterate over properties
for prop, value in oak_stairs.properties():
    print(f"  {prop}={value}")

# Create modified copy with different properties
south_stairs = oak_stairs.with_properties(facing="south")
print(south_stairs["facing"])  # south

# Create copy with different block id (keeping properties)
spruce_stairs = oak_stairs.with_id("minecraft:spruce_stairs")
print(spruce_stairs.id)  # minecraft:spruce_stairs

# Remove a property by setting to None
no_waterlog = oak_stairs.with_properties(waterlogged=None)
```

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

### Iterate Over Region Coordinates

Source: https://context7.com/smylermc/litemapy/llms.txt

Utilizes helper methods for coordinate iteration to generate a sphere and print a cross-section of a region.

```python
from litemapy import Schematic, Region, BlockState

# Create a region
region = Region(0, 0, 0, 21, 21, 21)
schematic = region.as_schematic(name="Sphere")

block = BlockState("minecraft:light_blue_concrete")
center = 10

# Iterate using block_positions() for all coordinates
for x, y, z in region.block_positions():
    # Calculate distance from center
    distance = ((x - center)**2 + (y - center)**2 + (z - center)**2) ** 0.5
    if round(distance) <= 10:
        region[x, y, z] = block

# Save and reload
schematic.save("sphere.litematic")
schematic = Schematic.load("sphere.litematic")
region = list(schematic.regions.values())[0]

# Print a cross-section using individual range iterators
print("Cross-section at y=10:")
for x in region.range_x():
    for z in region.range_z():
        block = region[x, 10, z]
        if block.id == "minecraft:air":
            print(" ", end="")
        else:
            print("#", end="")
    print()
```

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

### Mass Block Replacement with filter()

Source: https://context7.com/smylermc/litemapy/llms.txt

Performs efficient block replacement by applying a transformation function to the region's palette.

```python
from litemapy import Schematic, BlockState

# Define replacement mapping
REPLACEMENTS = {
    "minecraft:stone": BlockState("minecraft:light_gray_stained_glass"),
    "minecraft:dirt": BlockState("minecraft:brown_stained_glass"),
    "minecraft:grass_block": BlockState("minecraft:green_stained_glass"),
    "minecraft:water": BlockState("minecraft:blue_stained_glass"),
    "minecraft:sand": BlockState("minecraft:yellow_stained_glass"),
    "minecraft:gravel": BlockState("minecraft:gray_stained_glass"),
    "minecraft:oak_log": BlockState("minecraft:brown_stained_glass"),
    "minecraft:oak_leaves": BlockState("minecraft:lime_stained_glass"),
}

def transform_to_glass(block_state: BlockState) -> BlockState:
    """Transform blocks to stained glass equivalents."""
    replacement = REPLACEMENTS.get(block_state.id)
    if replacement:
        return replacement
    # Keep unknown blocks unchanged
    return block_state

# Load and transform schematic
schematic = Schematic.load("terrain.litematic")

for region_name, region in schematic.regions.items():
    print(f"Processing region: {region_name}")
    print(f"  Volume: {region.volume()} blocks")
    print(f"  Non-air before: {region.count_blocks()}")

    # Apply transformation (operates on palette, very fast)
    region.filter(transform_to_glass)

    print(f"  Non-air after: {region.count_blocks()}")

schematic.save("terrain_glass.litematic")
```

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

### Accessing Block State Properties

Source: https://github.com/smylermc/litemapy/blob/master/CHANGELOG.md

Access properties directly from the block state object using bracket notation.

```python
blockstate["propertyname"]
```

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

### Replacing Specific Blocks with replace()

Source: https://context7.com/smylermc/litemapy/llms.txt

Replaces all occurrences of a specific block state with another, including support for block properties.

```python
from litemapy import Schematic, BlockState

# Load schematic
schematic = Schematic.load("build.litematic")

# Define blocks
old_block = BlockState("minecraft:cobblestone")
new_block = BlockState("minecraft:stone_bricks")

# Replace in all regions
for region_name, region in schematic.regions.items():
    # Check if the block exists in the region first
    if old_block in region:
        print(f"Replacing cobblestone in region '{region_name}'")
        region.replace(old_block, new_block)

# Replace block with properties (must match exactly)
old_stairs = BlockState("minecraft:oak_stairs", facing="north", half="bottom", shape="straight", waterlogged="false")
new_stairs = BlockState("minecraft:spruce_stairs", facing="north", half="bottom", shape="straight", waterlogged="false")

for region in schematic.regions.values():
    region.replace(old_stairs, new_stairs)

schematic.save("build_updated.litematic")
```

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

### Testing Block Presence

Source: https://github.com/smylermc/litemapy/blob/master/CHANGELOG.md

Use the 'in' keyword to check if a specific block state exists within a region.

```python
burning = BlockState("minecraft:fire") in region
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.