### Initialize and Configure Animated DMI State

Source: https://context7.com/bobbah/dmisharp/llms.txt

Use this to create animated states, set individual frame delays, configure looping, rewind, and movement properties. Ensure all frames are set and delays match the frame count before saving.

```csharp
using DMISharp;
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.PixelFormats;

using var dmi = new DMIFile(32, 32);

// Create an animated state
var animState = new DMIState("flame", DirectionDepth.One, frames: 4, frameWidth: 32, frameHeight: 32);

// Set frame images
for (int i = 0; i < 4; i++)
{
    var img = Image.Load<Rgba32>($"flame_{i}.png");
    animState.SetFrame(img, i);
}

// Initialize delay array (creates animation capability)
animState.InitializeDelay();

// Set individual frame delays (units are 100ms ticks)
animState.SetDelay(frame: 0, delay: 1.0);  // 100ms
animState.SetDelay(frame: 1, delay: 1.5);  // 150ms
animState.SetDelay(frame: 2, delay: 1.0);  // 100ms
animState.SetDelay(frame: 3, delay: 2.0);  // 200ms

// Or set delays with an array
animState.SetDelay(new double[] { 1.0, 1.5, 1.0, 2.0 });

// Set animation loop count (0 = infinite)
animState.SetLoop(0);

// Enable rewind (animation plays forward then backward)
animState.SetRewind(true);

// Enable movement flag (animation only plays when object moves)
animState.SetMovement(false);

// Check if state is animated
Console.WriteLine($"Is Animated: {animState.IsAnimated()}");

// Check if ready to save (all frames present, delays match frame count)
Console.WriteLine($"Ready to Save: {animState.IsReadyForSave()}");

dmi.AddState(animState);
dmi.Save(@"output/animated.dmi");
```

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

### Create New DMI File with States from Images

Source: https://github.com/bobbah/dmisharp/blob/master/README.md

Creates a new DMI file with specified dimensions and adds states derived from source image files. Each state is initialized with a single frame.

```csharp
using var newDMI = new DMIFile(32, 32)
var sourceData = new List<string>() { "sord", "sordvert", "steve32" };

foreach (var source in sourceData)
{
    var img = Image.Load<Rgba32>($@
```

```csharp
Data/Input/SourceImages/{source}.png")
    var newState = new DMIState(source, DirectionDepth.One, 1, 32, 32);
    newState.SetFrame(img, 0);
    newDMI.AddState(newState);
}

newDMI.Save(@"Data/Output/minecraft.dmi");
```

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

### Create New DMI File Programmatically

Source: https://context7.com/bobbah/dmisharp/llms.txt

Instantiate DMIFile with desired frame dimensions and add states. Each state can be populated with image data loaded via ImageSharp. Ensure the DMIFile is saved only if CanSave() returns true.

```csharp
using DMISharp;
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.PixelFormats;

// Create a new DMI file with 32x32 pixel states
using var newDMI = new DMIFile(32, 32);

// Load source images and create states
var sourceImages = new[] { "character", "weapon", "item" };

foreach (var source in sourceImages)
{
    // Load image using ImageSharp
    var img = Image.Load<Rgba32>($"sprites/{source}.png");

    // Create a new state with 1 direction and 1 frame
    var newState = new DMIState(source, DirectionDepth.One, frames: 1, frameWidth: 32, frameHeight: 32);

    // Set the frame image for direction South (default), frame 0
    newState.SetFrame(img, frame: 0);

    // Add state to DMI file
    newDMI.AddState(newState);
}

// Verify file is ready to save
if (newDMI.CanSave())
{
    newDMI.Save(@"output/sprites.dmi");
}
```

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

### Manage State Directions and Frames

Source: https://context7.com/bobbah/dmisharp/llms.txt

Create states with specific DirectionDepth and frame counts. Frames can be set and retrieved for individual directions. Direction depth and frame count can be modified, potentially deleting frames if downsizing.

```csharp
using DMISharp;
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.PixelFormats;

// Create a 4-directional animated state
using var dmi = new DMIFile(32, 32);

// Create state with 4 directions and 3 animation frames
var walkState = new DMIState("walk", DirectionDepth.Four, frames: 3, frameWidth: 32, frameHeight: 32);

// Set frames for each direction (South, North, East, West)
var directions = new[] { StateDirection.South, StateDirection.North, StateDirection.East, StateDirection.West };

foreach (var dir in directions)
{
    for (int frame = 0; frame < 3; frame++)
    {
        var img = Image.Load<Rgba32>($"walk/{dir}_{frame}.png");
        walkState.SetFrame(img, dir, frame);
    }
}

dmi.AddState(walkState);

// Later, retrieve a specific frame
var southFrame0 = walkState.GetFrame(StateDirection.South, frame: 0);
var northFrame1 = walkState.GetFrame(StateDirection.North, frame: 1);

// Change direction depth of existing state (will delete frames if downsizing)
walkState.SetDirectionDepth(DirectionDepth.Eight);

// Change frame count (will delete frames if reducing)
walkState.SetFrameCount(5);

dmi.Save(@"output/walk_sprites.dmi");
```

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

### Ingest DMI File from Path

Source: https://github.com/bobbah/dmisharp/blob/master/README.md

Use this to load a DMI file directly from its file path. Remember to dispose of the DMIFile object as it uses unmanaged memory.

```csharp
using var file = new DMIFile("test.dmi")
// do cool things
```

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

### Create and Modify DMI State

Source: https://github.com/bobbah/dmisharp/blob/master/README.md

Demonstrates creating a new DMI file, adding a state, and then modifying its direction depth and frame count. Ensure all frames for the new direction depth are added before saving.

```csharp
using var newDMI = new DMIFile(32, 32)

// Create state
var img = Image.Load<Rgba32>($@
```

```csharp
Data/Input/SourceImages/steve32.png")
var newState = new DMIState("steve32", DirectionDepth.One, 1, 32, 32);
newState.SetFrame(img, 0);
newDMI.AddState(newState);

// Modifying state
newDMI.States.First().SetDirectionDepth(DirectionDepth.Four);
newDMI.States.First().SetFrameCount(10);

// At this point you would add the new frames for each direction, otherwise
// you cannot save the file.

// Saving
newDMI.Save(@"Data/Output/minecraft.dmi");
```

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

### Load DMI File from Path or Stream

Source: https://context7.com/bobbah/dmisharp/llms.txt

Use DMIFile constructors to load DMI files from a file path or a MemoryStream. Ensure DMIFile objects are disposed as they use unmanaged memory.

```csharp
using DMISharp;

// Load DMI file from a file path
using var file = new DMIFile(@"path/to/sprites.dmi");

// Access file metadata
Console.WriteLine($"Frame dimensions: {file.Metadata.FrameWidth}x{file.Metadata.FrameHeight}");
Console.WriteLine($"Number of states: {file.States.Count}");

// Load DMI file from a stream (e.g., from database or network)
using var memoryStream = new MemoryStream(dmiFileBytes);
using var fileFromStream = new DMIFile(memoryStream);

// Iterate through all states
foreach (var state in file.States)
{
    Console.WriteLine($"State: {state.Name}, Dirs: {state.Dirs}, Frames: {state.Frames}");
    Console.WriteLine($"Direction Depth: {state.DirectionDepth}");
    Console.WriteLine($"Is Animated: {state.IsAnimated()}");
}
```

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

### Ingest DMI File from Stream

Source: https://github.com/bobbah/dmisharp/blob/master/README.md

Load a DMI file from a stream, such as data retrieved from a database. Ensure the stream is properly disposed.

```csharp
// Getting a memory stream from a database with the DMI file's data in the response
using var dmiData = database.GetFile("test.dmi")
using var file = new DMIFile(dmiData)
// do more cool things
```

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

### Sort DMI States Alphabetically or by Custom Criteria

Source: https://context7.com/bobbah/dmisharp/llms.txt

Organize DMI states for better management. States can be sorted alphabetically by name or using a custom comparer, such as by frame count.

```csharp
using DMISharp;
using System.Collections.Generic;

using var file = new DMIFile(@"messy_sprites.dmi");

// Sort states alphabetically by name
file.SortStates();

// Save sorted file
file.Save(@"sorted_sprites.dmi");

// Or use a custom comparer
public class FrameCountComparer : IComparer<DMIState>
{
    public int Compare(DMIState? x, DMIState? y)
    {
        if (x == null || y == null) return 0;
        return x.TotalFrames.CompareTo(y.TotalFrames);
    }
}

using var file2 = new DMIFile(@"sprites.dmi");
file2.SortStates(new FrameCountComparer());

// Save to memory stream instead of file
using var memoryStream = new MemoryStream();
file2.Save(memoryStream);
byte[] dmiBytes = memoryStream.ToArray();
```

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

### Export Animated DMI States to GIF

Source: https://context7.com/bobbah/dmisharp/llms.txt

Export animated DMI states as GIF files for previews or documentation. Supports exporting specific directions or all directions with custom GIF encoder options.

```csharp
using DMISharp;
using SixLabors.ImageSharp.Formats.Gif;

using var file = new DMIFile(@"sprites/characters.dmi");

// Find an animated state by name
var animatedState = file.States.First(x => x.Name == "walk" && x.IsAnimated());

// Export GIF for a specific direction
using var gifStream = File.OpenWrite(@"output/walk_south.gif");
animatedState.SaveAnimatedGIF(gifStream, StateDirection.South);

// Export GIFs for all directions
for (var dir = StateDirection.South; dir <= StateDirection.West; dir++)
{
    using var fs = File.OpenWrite($"output/walk_{dir}.gif");
    animatedState.SaveAnimatedGIF(fs, dir);
}

// Use custom GIF encoder options
var customEncoder = new GifEncoder()
{
    Quantizer = new SixLabors.ImageSharp.Processing.Processors.Quantization.OctreeQuantizer(
        new SixLabors.ImageSharp.Processing.Processors.Quantization.QuantizerOptions()
        {
            Dither = null  // Disable dithering for pixel art
        })
};

using var customGifStream = File.OpenWrite(@"output/custom_walk.gif");
animatedState.SaveAnimatedGIF(customGifStream, StateDirection.South, customEncoder);

// Get animated image object directly for further processing
using var animatedImage = animatedState.GetAnimated(StateDirection.South);
// Process animatedImage as needed...
```

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

### Merge DMI Files with Sprite Sheets

Source: https://context7.com/bobbah/dmisharp/llms.txt

Import states from multiple DMI files into a target DMI file. Ensure all source files have matching frame dimensions to the target for successful import. Returns the number of states added.

```csharp
using DMISharp;

// Create target DMI file with specific dimensions
using var mergedDMI = new DMIFile(32, 32);

// Import states from multiple source files
using var characterFile = new DMIFile(@"sprites/characters.dmi");
using var itemFile = new DMIFile(@"sprites/items.dmi");
using var effectFile = new DMIFile(@"sprites/effects.dmi");

// ImportStates moves states from source to target (transfers ownership)
int charsAdded = mergedDMI.ImportStates(characterFile);
int itemsAdded = mergedDMI.ImportStates(itemFile);
int effectsAdded = mergedDMI.ImportStates(effectFile);

Console.WriteLine($"Merged {charsAdded + itemsAdded + effectsAdded} total states");
Console.WriteLine($"Final state count: {mergedDMI.States.Count}");

// Save merged file
mergedDMI.Save(@"output/all_sprites.dmi");

// Note: ImportStates returns 0 if frame dimensions don't match
using var wrongSizeDMI = new DMIFile(64, 64);  // Different size
int added = mergedDMI.ImportStates(wrongSizeDMI);  // Returns 0
```

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

### Sort DMI States Alphabetically and Save

Source: https://github.com/bobbah/dmisharp/blob/master/README.md

Sorts the states within a DMI file alphabetically and saves the modified file. This is useful for organizing states.

```csharp
using var file = new DMIFile("unsorted_states.dmi")
file.SortStates();
file.Save("sorted_states.dmi");
```

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

### Sort DMI States with Custom Comparer and Save to Stream

Source: https://github.com/bobbah/dmisharp/blob/master/README.md

Sorts DMI states using a custom comparison logic and saves the result to a memory stream. This allows for flexible sorting criteria.

```csharp
using var stream = new MemoryStream()
using var file = new DMIFile("unsorted_states.dmi")
file.SortStates(new CoolCustomComparer());
file.Save(stream);
```

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

### Access DMI File and State Metadata

Source: https://context7.com/bobbah/dmisharp/llms.txt

Retrieve detailed metadata about DMI files and individual states, including version, dimensions, frame counts, and animation properties. Raw metadata can also be extracted from a stream.

```csharp
using DMISharp;
using DMISharp.Metadata;
using System.IO;

using var file = new DMIFile(@"sprites.dmi");

// Access file-level metadata
DMIMetadata meta = file.Metadata;
Console.WriteLine($"BYOND Version: {meta.Version}");
Console.WriteLine($"Frame Width: {meta.FrameWidth}");
Console.WriteLine($"Frame Height: {meta.FrameHeight}");
Console.WriteLine($"Total States: {meta.States.Count}");

// Access state-level metadata
foreach (var state in file.States)
{
    StateMetadata stateMeta = state.Data;

    Console.WriteLine($"\nState: {stateMeta.State}");
    Console.WriteLine($"  Directions: {stateMeta.Dirs}");
    Console.WriteLine($"  Frames: {stateMeta.Frames}");
    Console.WriteLine($"  Total Frames: {state.TotalFrames}");
    Console.WriteLine($"  Frame Capacity: {state.FrameCapacity}");

    if (stateMeta.Delay != null)
    {
        Console.WriteLine($"  Animation Delays: [{string.Join(", ", stateMeta.Delay)}]");
        Console.WriteLine($"  Loop Count: {stateMeta.Loop}");
        Console.WriteLine($"  Rewind: {stateMeta.Rewind}");
        Console.WriteLine($"  Movement: {stateMeta.Movement}");
    }

    if (stateMeta.Hotspots != null)
    {
        Console.WriteLine($"  Hotspots: {stateMeta.Hotspots.Count} defined");
    }
}

// Extract raw DMI metadata from a stream
using var stream = File.OpenRead(@"sprites.dmi");
ReadOnlySpan<char> rawMetadata = DMIMetadata.GetDMIMetadata(stream);
Console.WriteLine($"Raw metadata length: {rawMetadata.Length}");
```

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

### Modify Existing DMI States

Source: https://context7.com/bobbah/dmisharp/llms.txt

Add, remove, and modify states within a DMI file. The library validates state dimensions and frame completeness before saving. Remember to dispose of removed states.

```csharp
using DMISharp;
using SixLabors.ImageSharp;
using SixLabors.ImageSharp.PixelFormats;
using System.Linq;

using var file = new DMIFile(@"sprites.dmi");

// Find and remove a state by name
var oldState = file.States.FirstOrDefault(x => x.Name == "old_sprite");
if (oldState != null)
{
    file.RemoveState(oldState);
    oldState.Dispose();  // Always dispose removed states
}

// Modify an existing state's direction depth
var state = file.States.First(x => x.Name == "character");

// Upgrade from 1-direction to 4-direction (adds empty frame slots)
state.SetDirectionDepth(DirectionDepth.Four);

// Must fill new direction frames before saving
for (var dir = StateDirection.North; dir <= StateDirection.West; dir++)
{
    for (int frame = 0; frame < state.Frames; frame++)
    {
        var img = Image.Load<Rgba32>($"character_{dir}_{frame}.png");
        state.SetFrame(img, dir, frame);
    }
}

// Delete a specific frame
state.DeleteFrame(StateDirection.South, frame: 0);

// Replace a frame with new image
var newImage = Image.Load<Rgba32>(@"new_frame.png");
state.SetFrame(newImage, StateDirection.South, frame: 0);

// Clear all states from file
file.ClearStates();

// Validate before saving
if (file.CanSave())
{
    file.Save(@"output/modified.dmi");
}
else
{
    Console.WriteLine("File not ready - missing frames or invalid state");
}
```

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