### Command Line Quick Start: JSON Configuration

Source: https://github.com/boristhebrave/debroglie/blob/master/docs/articles/index.md

Example JSON configuration file for the DeBroglie command-line tool. This setup uses the 'overlapping' model with a specified input image and output file.

```json
{
    "src": "sewers.png",
    "dest": "generated-sewers.png",
    "model": {
        "type": "overlapping",
        "n": 3
    },
    "periodicInput": true,
    "periodic": true,
    "symmetry": 8
}
```

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

### C# Quick Start: Construct and Run WFC

Source: https://github.com/boristhebrave/debroglie/blob/master/docs/articles/index.md

Demonstrates constructing the necessary objects and running the Wave Function Collapse algorithm in C#. Ensure the DeBroglie library is referenced.

```csharp
// Define some sample data
ITopoArray<char> sample = TopoArray.Create(new[]
{
    new[]{ '_', '_', '_'},
    new[]{ '_', '*', '_'},
    new[]{ '_', '_', '_'},
}, periodic: false);
// Specify the model used for generation
var model = new AdjacentModel(sample.ToTiles());
// Set the output dimensions
var topology = new GridTopology(10, 10, periodic: false);
// Acturally run the algorithm
var propagator = new TilePropagator(model, topology);
var status = propagator.Run();
if (status != Resolution.Decided) throw new Exception("Undecided");
var output = propagator.ToValueArray<char>();
// Display the results
for (var y = 0; y < 10; y++)
{
    for (var x = 0; x < 10; x++)
    {
        System.Console.Write(output.Get(x, y));
    }
    System.Console.WriteLine();
}
```

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

### C# Library Example for Tile Rotation Initialization

Source: https://github.com/boristhebrave/debroglie/blob/master/docs/articles/rotation.md

A concise example of initializing a TileRotation object with specified rotational and reflectional symmetries.

```csharp
var rotations = new TileRotation(4, true);
```

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

### C# Library Example for Tile Rotation Builder

Source: https://github.com/boristhebrave/debroglie/blob/master/docs/articles/rotation.md

Demonstrates initializing a TileRotationBuilder and adding tiles with specified rotations. This is used when generating new tiles as needed.

```csharp
var builder = new TileRotationBuilder(4, true, TileRotationTreatment.Generated);
// tile 1 reflects in x-axis to give itself.
builder.Add(tile1, new Rotation(0, true), tile1);
// We haven't added a rotation, so a new rotation tile will
// be created when DeBroglie tries to rotate tile 1.

// You can also specify self-symmetries like so
//builder.AddSymmetry(tile1, TileSymmetry.T);

var rotations = builder.Build();
... 
// Add a new sample to the model, using all
// eight rotations and reflections, generating new tiles as needed
model.AddSample(sample,  rotations)
```

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

### Command Line Quick Start: Execution

Source: https://github.com/boristhebrave/debroglie/blob/master/docs/articles/index.md

Command to run the DeBroglie command-line executable with a specified JSON configuration file. Ensure the paths to the executable and JSON file are correct.

```bash
path_to_debroglie/DeBroglie.Console.exe path_to_json/sewers.json
```

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

### JSON Configuration Example for Tile Rotation

Source: https://github.com/boristhebrave/debroglie/blob/master/docs/articles/rotation.md

Shows how to configure tile rotation and symmetry properties within a JSON configuration file. The `rotationTreatment` is set to 'generated' to allow new tiles to be created.

```json
{
    "...",
    "rotationTreatment": "generated",

    "rotationalSymmetry": 4,
    "reflectionalSymmetry": true,
    "tiles": [
        // tile 1 reflects in x-axis to give itself.
        {"value": 1, "reflectX": 1}
        // We haven't added a rotation, so a new rotation tile will
        // be created when DeBroglie tries to rotate tile 1.

        // You can also specify self-symmetries like so
        //{"value": 1, "tileSymmetry": "T"}
    ]
}
```

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

### Guaranteeing Specific Features with FixedTileConstraint

Source: https://context7.com/boristhebrave/debroglie/llms.txt

FixedTileConstraint places a given tile at a specific location or a random legal location at the start of generation, ensuring the feature always appears.

```csharp
using DeBroglie.Constraints;

var turretTile = new Tile("turret");
var bossTile   = new Tile("boss_room");

var constraints = new ITileConstraint[]
{
    // Always place a turret at (5, 5)
    new FixedTileConstraint
    {
        Tile  = turretTile,
        Point = new Point(5, 5),
    },
    // Place a boss room at a randomly chosen legal location
    new FixedTileConstraint
    {
        Tile = bossTile,
        // No Point set → random legal placement
    },
};

var propagator = new TilePropagator(
    model, topology,
    backtrack: true,
    constraints: constraints);
propagator.Run();
```

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

### Basic TilePropagator Usage for WFC Generation

Source: https://context7.com/boristhebrave/debroglie/llms.txt

Demonstrates the core steps of using TilePropagator to generate a 10x10 grid. This includes building a sample array, creating an AdjacentModel, defining the output topology, running the generation, and retrieving the results. Progress reporting is also shown.

```csharp
using DeBroglie;
using DeBroglie.Models;
using DeBroglie.Topo;

// 1. Build a sample array
ITopoArray<char> sample = TopoArray.Create(new[]
{
    new[] { '_', '_', '_' },
    new[] { '_', '*', '_' },
    new[] { '_', '_', '_' },
}, periodic: false);

// 2. Create a model from the sample
var model = new AdjacentModel(sample.ToTiles());

// 3. Define output dimensions (10×10, non-periodic)
var topology = new GridTopology(10, 10, periodic: false);

// 4. Run generation
var propagator = new TilePropagator(model, topology);
Resolution status = propagator.Run();

if (status != Resolution.Decided)
    throw new Exception($"Generation failed: {propagator.ContradictionReason}");

// 5. Retrieve output
ITopoArray<char> output = propagator.ToValueArray<char>();
for (var y = 0; y < 10; y++)
{
    for (var x = 0; x < 10; x++)
        Console.Write(output.Get(x, y));
    Console.WriteLine();
}

// Progress reporting (useful for async workflows)
Console.WriteLine($"Backtracks: {propagator.BacktrackCount}");
Console.WriteLine($"Progress: {propagator.GetProgress():P0}");

```

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

### TilePropagator - Basic Usage

Source: https://context7.com/boristhebrave/debroglie/llms.txt

Demonstrates the fundamental steps to initialize and run the TilePropagator for Wave Function Collapse generation. This includes creating a sample, defining a model and topology, and executing the generation process.

```APIDOC
## TilePropagator — main entry point

`TilePropagator` orchestrates the WFC generation loop. Construct it with a model, a topology, and optional constraints and options, then call `Run()` to generate a complete output, or call `Step()` to advance one tile at a time. Results are retrieved as `ITopoArray<T>` via `ToValueArray<T>()`.

```csharp
using DeBroglie;
using DeBroglie.Models;
using DeBroglie.Topo;

// 1. Build a sample array
ITopoArray<char> sample = TopoArray.Create(new[]
{
    new[] { '_', '_', '_' },
    new[] { '_', '*', '_' },
    new[] { '_', '_', '_' },
}, periodic: false);

// 2. Create a model from the sample
var model = new AdjacentModel(sample.ToTiles());

// 3. Define output dimensions (10x10, non-periodic)
var topology = new GridTopology(10, 10, periodic: false);

// 4. Run generation
var propagator = new TilePropagator(model, topology);
Resolution status = propagator.Run();

if (status != Resolution.Decided)
    throw new Exception($"Generation failed: {propagator.ContradictionReason}");

// 5. Retrieve output
ITopoArray<char> output = propagator.ToValueArray<char>();
for (var y = 0; y < 10; y++)
{
    for (var x = 0; x < 10; x++)
        Console.Write(output.Get(x, y));
    Console.WriteLine();
}

// Progress reporting (useful for async workflows)
Console.WriteLine($"Backtracks: {propagator.BacktrackCount}");
Console.WriteLine($"Progress: {propagator.GetProgress():P0}");
```
```

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

### Advanced TilePropagator Configuration with Options

Source: https://context7.com/boristhebrave/debroglie/llms.txt

Shows how to use TilePropagatorOptions for fine-grained control over WFC generation. This includes setting backtracking strategy, random number generation, cell/tile picking algorithms, and attaching constraints. This approach is useful for reproducible or customized generation processes.

```csharp
using DeBroglie;
using DeBroglie.Wfc;

var options = new TilePropagatorOptions
{
    // Use backjump (smarter than naive backtrack, fewer retries)
    BacktrackType = BacktrackType.Backjump,
    MaxBacktrackDepth = 50,

    // Reproducible generation with a seeded RNG
    RandomDouble = new Random(42).NextDouble,

    // Pick cells in min-entropy order (standard WFC behaviour)
    IndexPickerType = IndexPickerType.HeapMinEntropy,

    // Pick tiles weighted by their frequency in the sample
    TilePickerType = TilePickerType.Weighted,

    // Attach constraints (see Constraints section)
    Constraints = new ITileConstraint[] { /* ... */ },
};

var propagator = new TilePropagator(model, topology, options);
var status = propagator.Run();

```

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

### Build NuGet Package

Source: https://github.com/boristhebrave/debroglie/blob/master/RELEASING.md

Use this command to build the NuGet package for the DeBroglie project. Ensure you are in the project directory.

```bash
dotnet pack -c Release DeBroglie
```

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

### Publish NuGet Package

Source: https://github.com/boristhebrave/debroglie/blob/master/RELEASING.md

Publish the built NuGet package to the NuGet repository. Replace `<api-key>` with your actual NuGet API key and `<version>` with the package version.

```bash
dotnet nuget push DeBroglie/bin/release/DeBroglie.<version>.nupkg -k <api-key> -s https://api.nuget.org/v3/index.json
```

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

### Configure 8 Rotations and Reflections for Single Pixels

Source: https://github.com/boristhebrave/debroglie/blob/master/docs/articles/rotation.md

Use this to specify all 8 rotations and reflections for single pixel or voxel tiles. The AddSample method will then use 8 copies of the sample.

```csharp
// Specifies we're using all 8 rotations and reflections
var rotations = new TileRotation(4, true);
// Add a new sample to the model, using 8 copies
model.AddSample(sample, rotations)
```

```javascript
{
    "src": "sample...",
    "rotationalSymmetry": 4,
    "reflectionalSymmetry": true,
}
```

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

### TilePropagatorOptions - Advanced Configuration

Source: https://context7.com/boristhebrave/debroglie/llms.txt

Explains how to use `TilePropagatorOptions` for advanced control over the generation process, including backtracking strategies, random number generation, cell and tile picking algorithms, and constraint management.

```APIDOC
## TilePropagatorOptions — advanced construction

`TilePropagatorOptions` provides fine-grained control over backtracking strategy, picker algorithms, seeded randomness, and per-cell weight overrides. Pass an options object to the second `TilePropagator` constructor instead of individual flags.

```csharp
using DeBroglie;
using DeBroglie.Wfc;

var options = new TilePropagatorOptions
{
    // Use backjump (smarter than naive backtrack, fewer retries)
    BacktrackType = BacktrackType.Backjump,
    MaxBacktrackDepth = 50,

    // Reproducible generation with a seeded RNG
    RandomDouble = new Random(42).NextDouble,

    // Pick cells in min-entropy order (standard WFC behaviour)
    IndexPickerType = IndexPickerType.HeapMinEntropy,

    // Pick tiles weighted by their frequency in the sample
    TilePickerType = TilePickerType.Weighted,

    // Attach constraints (see Constraints section)
    Constraints = new ITileConstraint[] { /* ... */ },
};

var propagator = new TilePropagator(model, topology, options);
var status = propagator.Run();
```
```

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

### AdjacentModel: Learn from Sample or Declare Pairs

Source: https://context7.com/boristhebrave/debroglie/llms.txt

Demonstrates creating an AdjacentModel either by learning from a sample array or by explicitly declaring allowed tile adjacencies for cardinal directions. Includes setting tile frequencies.

```csharp
using DeBroglie;
using DeBroglie.Models;
using DeBroglie.Topo;

// --- Option A: learn from a sample ---
ITopoArray<char> sample = TopoArray.Create(new[]
{
    new[] { 'G', 'G', 'W' },
    new[] { 'G', 'W', 'W' },
    new[] { 'W', 'W', 'W' },
}, periodic: false);

var model = new AdjacentModel(sample.ToTiles());

// --- Option B: declare pairs explicitly ---
var model2 = new AdjacentModel(DirectionSet.Cartesian2d);
var grass = new Tile('G');
var water = new Tile('W');
var sand  = new Tile('S');

// Grass can be left of grass or sand; water can be left of water or sand
model2.AddAdjacency(new[] { grass }, new[] { grass, sand }, 1, 0, 0);
model2.AddAdjacency(new[] { water }, new[] { water, sand }, 1, 0, 0);
model2.AddAdjacency(new[] { sand  }, new[] { grass, water, sand }, 1, 0, 0);
// Ensure vertical pairs too
model2.AddAdjacency(new[] { grass }, new[] { grass, sand }, 0, 1, 0);
model2.AddAdjacency(new[] { water }, new[] { water, sand }, 0, 1, 0);
model2.AddAdjacency(new[] { sand  }, new[] { grass, water, sand }, 0, 1, 0);

// Set uniform frequency so all tiles appear equally often
model2.SetUniformFrequency();

// Boost the frequency of grass tiles by 2×
model2.MultiplyFrequency(grass, 2.0);

var topology = new GridTopology(20, 20, periodic: false);
var propagator = new TilePropagator(model2, topology);
propagator.Run();
```

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

### Pre-seeding Tile Constraints with Ban and Select

Source: https://context7.com/boristhebrave/debroglie/llms.txt

Use Ban and Select before calling Run() to fix or forbid specific tiles at given coordinates. This is useful for ensuring certain features always appear or are absent.

```csharp
var propagator = new TilePropagator(model, new GridTopology(15, 15, false));

var doorTile  = new Tile('D');
var wallTile  = new Tile('#');
var floorTile = new Tile('.');

// Force a door at (7, 0) — the centre of the top edge
propagator.Select(7, 0, 0, doorTile);

// Ban walls from the entire bottom row
for (int x = 0; x < 15; x++)
    propagator.Ban(x, 14, 0, wallTile);

// Force the floor at a specific room centre
propagator.Select(7, 7, 0, floorTile);

var status = propagator.Run();

// Inspect a single cell after generation
bool isDoor = propagator.IsSelected(7, 0, 0, doorTile);
bool isWallBanned = propagator.IsBanned(0, 14, 0, wallTile);
```

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

### Convert TopoArray to Tile Array and Read Values

Source: https://context7.com/boristhebrave/debroglie/llms.txt

Shows how to convert an existing ITopoArray<T> to an ITopoArray<Tile> and retrieve values using coordinates. The DeBroglie.Topo namespace is required.

```csharp
// Convert any ITopoArray<T> to ITopoArray<Tile> (required by models)
ITopoArray<Tile> tileArray = arr2d.ToTiles();

// Read values by coordinate
int val = arr2d.Get(1, 2);        // x=1, y=2
int val3 = arr3d.Get(0, 1, 1);   // x=0, y=1, z=1
```

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

### Create TopoArray from 2D and 3D C# Arrays

Source: https://context7.com/boristhebrave/debroglie/llms.txt

Demonstrates creating non-periodic TopoArray instances from 2D and 3D C# arrays. Ensure the DeBroglie.Topo namespace is included.

```csharp
using DeBroglie.Topo;

// Create from a 2D C# array (non-periodic)
ITopoArray<int> arr2d = TopoArray.Create(new[,]
{
    { 1, 2, 1 },
    { 2, 1, 2 },
    { 1, 2, 1 },
}, periodic: false);

// Create from a 3D C# array
ITopoArray<int> arr3d = TopoArray.Create(new int[,,]
{
    { { 0, 1 }, { 1, 0 } },
    { { 1, 0 }, { 0, 1 } },
},
periodic: false);
```

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

### Run DeBroglie Console Executable

Source: https://github.com/boristhebrave/debroglie/blob/master/docs/articles/config_files.md

Invoke the DeBroglie console application with a JSON configuration file. This is the primary way to use the tool from the command line.

```bash
./DeBroglie.Console.exe myconfig.json
```

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

### Define Tile Rotations and Reflections for Complete Tilesets

Source: https://github.com/boristhebrave/debroglie/blob/master/docs/articles/rotation.md

Use a TileRotationBuilder to define how specific tiles rotate and reflect into each other. This is useful when your tileset includes explicit rotations and reflections. The AddSample method will then use all eight rotations and reflections, applying the specified transformations.

```csharp
var builder = new TileRotationBuilder(4, true);
// tile 1 rotates clockwise to give tile 2
builder.Add(tile1, new Rotation(90), tile2); 
// tile 1 reflects in x-axis to give itself.
builder.Add(tile1, new Rotation(0, true), tile1);
var rotations = builder.Build();
... 
// Add a new sample to the model, using all
// eight rotations and reflections, replacing
// tiles as specified above
model.AddSample(sample, rotations)
```

```javascript
{
    ...
    "rotationalSymmetry": 4,
    "reflectionalSymmetry": true,
    "tiles": [
        // tile 1 rotates clockwise to give tile 2
        // tile 1 reflects in x-axis to give itself.
        {"value": 1, "rotateCw": 2, "reflectX": 1}
    ]
}
```

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

### Implement Custom ITileConstraint in C#

Source: https://context7.com/boristhebrave/debroglie/llms.txt

Implement ITileConstraint to enforce custom logic not covered by built-in constraints. The Init method is called once, and Check is called after each tile placement.

```csharp
using DeBroglie;
using DeBroglie.Constraints;
using DeBroglie.Topo;

/// <summary>
/// Ensures the tile at the centre of the grid is always a specific tile.
/// </summary>
public class CentreTileConstraint : ITileConstraint
{
    private readonly Tile _centreRequired;

    public CentreTileConstraint(Tile centreRequired)
    {
        _centreRequired = centreRequired;
    }

    public void Init(TilePropagator propagator)
    {
        var topo = propagator.Topology as GridTopology;
        int cx = topo.Width  / 2;
        int cy = topo.Height / 2;
        // Force centre tile immediately
        var status = propagator.Select(cx, cy, 0, _centreRequired);
        if (status == Resolution.Contradiction)
            propagator.SetContradiction("Centre tile could not be placed", this);
    }

    public void Check(TilePropagator propagator)
    {
        // No incremental checks needed; Init handled it all
    }
}

// Usage
var constraints = new ITileConstraint[]
{
    new CentreTileConstraint(new Tile("boss_spawn")),
};
var propagator = new TilePropagator(model, topology, backtrack: true, constraints: constraints);
propagator.Run();
```

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

### Add Sample to AdjacentModel (C#)

Source: https://github.com/boristhebrave/debroglie/blob/master/docs/articles/adjacency.md

Use this method to initialize the AdjacentModel with a sample input, allowing it to automatically detect adjacency pairs.

```csharp
var model = new AdjacentModel();
ITopoArray<Tile> sample = ...;
model.AddSample(sample);
```

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

### Create TopoArray from a Function

Source: https://context7.com/boristhebrave/debroglie/llms.txt

Illustrates creating a TopoArray using a function that generates values based on coordinates. Requires a Topology object and the DeBroglie.Topo namespace.

```csharp
// Create from a function
var topology = new GridTopology(5, 5, false);
ITopoArray<double> noise = TopoArray.CreateByIndex(
    index =>
    {
        topology.GetCoord(index, out var x, out var y, out var z);
        return Math.Sin(x) * Math.Cos(y);
    },
    topology);
```

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

### Construct a Rotated Tile Instance

Source: https://github.com/boristhebrave/debroglie/blob/master/docs/articles/rotation.md

Create a new Tile object that represents a rotated version of an existing tile. This is useful when you need to directly reference a rotated tile.

```csharp
new Tile(new RotatedTile(oldTile, rotation));
```

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

### GridTopology: Define Output Space and Connectivity

Source: https://context7.com/boristhebrave/debroglie/llms.txt

Illustrates the creation of GridTopology objects for various grid shapes (2D square, 2D hex, 3D cube) and configurations, including periodic boundaries and cell masking. Shows index-coordinate conversion.

```csharp
using DeBroglie.Topo;

// 2D square, non-periodic (standard)
var topo2d = new GridTopology(width: 30, height: 20, periodic: false);

// 2D square, wraps on both axes (like a torus)
var torusTopology = new GridTopology(20, 20, periodic: true);

// 3D cube
var topo3d = new GridTopology(width: 10, height: 10, depth: 10, periodic: false);

// 2D hex grid (pointy-side up convention)
var hexTopo = new GridTopology(
    DirectionSet.Hexagonal2d,
    width: 15, height: 15,
    periodicX: false, periodicY: false);

// Apply a mask to mark certain cells as unavailable
bool[] mask = new bool[30 * 20];
// Mark a circular area as active
for (int y = 0; y < 20; y++)
    for (int x = 0; x < 30; x++)
        mask[x + y * 30] = (x - 15) * (x - 15) + (y - 10) * (y - 10) < 80;

var maskedTopology = topo2d.WithMask(mask);

// Convenience index ↔ coordinate conversion
maskedTopology.GetCoord(idx: 35, out int cx, out int cy, out int cz);
int idx = maskedTopology.GetIndex(cx, cy, cz);
```

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

### Run DeBroglie Generation from JSON Config

Source: https://context7.com/boristhebrave/debroglie/llms.txt

The DeBroglie.Console.exe executable accepts JSON config files for use without writing C#. It supports all core library features through a declarative format.

```bash
# Run generation from a config file
./DeBroglie.Console.exe sewers.json
```

```json
{
    "src":  "sewers.png",
    "dest": "output.png",
    "model": {
        "type": "overlapping",
        "n": 3
    },
    "width":  48,
    "height": 48,
    "periodicInput": true,
    "periodic": true,
    "symmetry": 8,
    "backtrack": true,
    "constraints": [
        {
            "type": "border",
            "tile": "#FF0000",
            "sides": "ymax"
        },
        {
            "type": "path",
            "tiles": ["#0000FF"],
            "endPoints": [
                {"x": 0,  "y": 0},
                {"x": 47, "y": 47}
            ]
        },
        {
            "type": "fixedTile",
            "tile": "#FFFF00",
            "point": {"x": 24, "y": 24}
        }
    ],
    "tiles": [
        {
            "value": "#FF0000",
            "multiplyFrequency": 0.5
        },
        {
            "value": 1,
            "rotateCw": 2,
            "reflectX": 1,
            "tileSymmetry": "T"
        }
    ],
    "adjacencies": [
        {"left": [1, 2], "right": [3, 4]},
        {"up":   [1],    "down":  [2]}
    ]
}
```

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

### Handle Tile Rotations and Reflections with TileRotation

Source: https://context7.com/boristhebrave/debroglie/llms.txt

TileRotation pre-processes samples to include rotational and reflective symmetries, effectively increasing the training data. TileRotationBuilder allows explicit configuration of tile-to-tile rotation mappings.

```csharp
using DeBroglie.Rot;

// --- Simple pixel/voxel case: all 8 symmetries (4 rotations + reflection) ---
var rotations = new TileRotation(rotationalSymmetry: 4, reflectionalSymmetry: true);
model.AddSample(sample.ToTiles(), rotations);

// --- Complete tileset: specify what each tile becomes under rotation ---
var builder = new TileRotationBuilder(4, true, TileRotationTreatment.Unchanged);

var cornerA = new Tile(1);  // top-left corner
var cornerB = new Tile(2);  // top-right corner
var cornerC = new Tile(3);  // bottom-right corner
var cornerD = new Tile(4);  // bottom-left corner

// tile 1 rotated 90° CW gives tile 2
builder.Add(cornerA, new Rotation(90),        cornerB);
// tile 1 reflected in x-axis gives tile 4
builder.Add(cornerA, new Rotation(0, true),   cornerD);
// DeBroglie infers all other combinations

var tileRotation = builder.Build();
model.AddSample(sample.ToTiles(), tileRotation);

// --- Incomplete tileset: generate missing rotated variants ---
var builder2 = new TileRotationBuilder(4, true, TileRotationTreatment.Generated);
var pathTile = new Tile(10);
// Mark tile as symmetric about the y-axis (T symmetry)
builder2.AddSymmetry(pathTile, TileSymmetry.T);
var tileRotation2 = builder2.Build();

// Reference a generated tile (e.g. pathTile rotated 90° CW)
var rotatedPath = new Tile(new RotatedTile(pathTile, new Rotation(90)));
```

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

### Define Tile Rotations with JSON Config

Source: https://github.com/boristhebrave/debroglie/blob/master/docs/articles/rotation.md

Configure tile rotations and reflections within the 'tiles' array in JSON. Use 'rotateCw' for clockwise rotation and 'reflectX' for x-axis reflection, specifying target tile values.

```javascript
{
    ...
    "tiles": [
        // tile 1 rotates clockwise to give tile 2
        // tile 1 reflects in x-axis to give itself.
        {"value": 1, "rotateCw": 2, "reflectX": 1}
    ]
}
```

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

### Define Tile Rotations with C# Library

Source: https://github.com/boristhebrave/debroglie/blob/master/docs/articles/rotation.md

Use TileRotationBuilder to define clockwise rotations and reflections between tiles. Specify the source tile, the rotation/reflection, and the target tile.

```csharp
var builder = new TileRotationBuilder(4, true);
// tile 1 rotates clockwise to give tile 2
builder.Add(tile1, new Rotation(90), tile2); 
// tile 1 reflects in x-axis to give itself.
builder.Add(tile1, new Rotation(0, true), tile1);
```

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

### Use Trackers for Efficient Generation State Observation

Source: https://context7.com/boristhebrave/debroglie/llms.txt

Trackers subscribe to internal propagator events for efficient state observation. Use them inside custom constraints for performance-critical operations instead of scanning the full output each Check call.

```csharp
using DeBroglie.Trackers;

// After constructing propagator (but before calling Run):
var tileSet = propagator.CreateTileSet(new[] { new Tile("lava") });

// SelectedTracker: O(1) query of banned/selected status per cell
var selectedTracker = propagator.CreateSelectedTracker(tileSet);

// SelectedChangeTracker: callback-driven, fired on every status change
var changeTracker = propagator.CreateSelectedChangeTracker(tileSet,
    new QuadstateChangedDelegate((index, before, after) =>
    {
        propagator.Topology.GetCoord(index, out var x, out var y, out var z);
        Console.WriteLine($"Cell ({x},{y}) lava status: {before} → {after}");
    }));

// ChangeTracker: cheap record of which indices changed last step
var genericChangeTracker = propagator.CreateChangeTracker();

propagator.Step();

// Query the selected tracker
var qs = selectedTracker.GetQuadstate(5, 5, 0);
// Quadstate.Yes = selected, No = banned, Maybe = undecided, Contradiction = impossible

// Trackers are invalidated when propagator.Clear() is called
```

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

### Add Combinatorial Adjacency Pairs (C#)

Source: https://github.com/boristhebrave/debroglie/blob/master/docs/articles/adjacency.md

Add adjacency pairs between groups of tiles, where any tile in the first group can be placed next to any tile in the second group along a specified axis.

```csharp
var model = new AdjacentModel();
var tile1 = new Tile(1);
var tile2 = new Tile(2);
var tile3 = new Tile(3);
var tile4 = new Tile(4);
model.AddAdjacency(new []{tile1, tile2}, new []{tile3, tile4}, 0, 1, 0);
```

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

### AdjacentModel Configuration (JSON)

Source: https://github.com/boristhebrave/debroglie/blob/master/docs/articles/adjacency.md

Configure the AdjacentModel using a JSON object, specifying the model type and a source for samples.

```json
{
    "model": {"type": "adjacent"},
    "src": "my_sample.png",
    ...
}
```

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

### OverlappingModel: Enforce n x n Structural Patterns

Source: https://context7.com/boristhebrave/debroglie/llms.txt

Shows how to use OverlappingModel to ensure that every n x n rectangle in the output matches a corresponding rectangle from the sample. Allows for rotation and reflection of sample patterns and frequency adjustments.

```csharp
using DeBroglie;
using DeBroglie.Models;
using DeBroglie.Rot;
using DeBroglie.Topo;

// Load a bitmap-style sample (each char = one tile/pixel)
var rawSample = new[,]
{
    { 'B', 'B', 'B', 'B', 'B' },
    { 'B', 'G', 'G', 'G', 'B' },
    { 'B', 'G', 'B', 'G', 'B' },
    { 'B', 'G', 'G', 'G', 'B' },
    { 'B', 'B', 'B', 'B', 'B' },
};
ITopoArray<char> sample = TopoArray.Create(rawSample, periodic: false);

// n=3: every 3×3 region in the output matches a 3×3 region in the sample
// Pass rotations to expand data (4 rotations + reflection = 8 variants)
var model = new OverlappingModel(3);
model.AddSample(sample.ToTiles(), new TileRotation(4, true));

// Reduce frequency of 'B' (background) to get more open areas
model.MultiplyFrequency(new Tile('B'), 0.5);

var topology = new GridTopology(20, 20, periodic: true);
var propagator = new TilePropagator(model, topology);
var status = propagator.Run();
Console.WriteLine(status); // Decided
```

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

### Add Combinatorial Adjacency Pairs (JSON)

Source: https://github.com/boristhebrave/debroglie/blob/master/docs/articles/adjacency.md

Configure combinatorial adjacency pairs in JSON, defining groups of tiles that can be placed adjacent to each other on specified axes.

```json
{
    ...
    "adjacencies": [
        {"up": [1, 2], "down": [3, 4]}
    ]
}
```

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

### Basic Rotational and Reflectional Symmetry Configuration

Source: https://github.com/boristhebrave/debroglie/blob/master/docs/articles/rotation.md

This JSON configuration sets the rotational symmetry to 4 and reflectional symmetry to true. Use this for basic configurations when rotating pixel or voxel arrays.

```json
{
    "rotationalSymmetry": 4,
    "reflectionalSymmetry": true,
}
```

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

### Enforce Symmetry with MirrorXConstraint and MirrorYConstraint

Source: https://context7.com/boristhebrave/debroglie/llms.txt

MirrorXConstraint and MirrorYConstraint enforce perfect symmetry in the generated output along the x-axis and y-axis, respectively. These constraints are useful for creating symmetrical patterns or structures.

```csharp
using DeBroglie.Constraints;

var constraints = new ITileConstraint[]
{
    new MirrorXConstraint(), // left-right symmetry
    // new MirrorYConstraint(), // top-bottom symmetry
};

var propagator = new TilePropagator(model, topology, constraints: constraints);
propagator.Run();
```

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

### Add Adjacency with Rotations (JSON)

Source: https://github.com/boristhebrave/debroglie/blob/master/docs/articles/adjacency.md

Configure adjacency pairs in JSON, along with rotational and reflectional symmetry settings. This enables automatic generation of adjacency pairs for rotated tiles.

```json
{
    ...
    "adjacencies": [
        {"left": [1], "down": [2]}
    ],
    "rotationalSymmetry": 4,
    "reflectionalSymmetry": true
}
```

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

### Generated Tile Naming Convention in JavaScript

Source: https://github.com/boristhebrave/debroglie/blob/master/docs/articles/rotation.md

In JavaScript configuration, generated tiles are represented by their original tile value followed by a rotation string. The string format is '!<x if reflected><rotation in degrees>'.

```javascript
oldTile!90
oldTile!x180
```

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

### Add Adjacency with Rotations (C#)

Source: https://github.com/boristhebrave/debroglie/blob/master/docs/articles/adjacency.md

Add adjacency pairs to the AdjacentModel, incorporating tile rotations by providing a rotation configuration. This allows for adjacency between rotated versions of tiles.

```csharp
var model = new AdjacentModel();
var rotations = tileRotationBuilder.Build();
var tile1 = new Tile(1);
var tile2 = new Tile(2);
model.AddAdjacency(new []{tile1}, new []{tile2}, 0, 1, 0, rotations);
```

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

### Add Single Adjacency Pair (JSON)

Source: https://github.com/boristhebrave/debroglie/blob/master/docs/articles/adjacency.md

Configure a single adjacency pair in JSON, specifying the 'left' and 'right' tiles that can be placed adjacent to each other.

```json
{
    ...
    "adjacencies": [
        {"left": [1], "right": [2]}
    ]
}
```

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

### Preventing Long Repetitive Runs with MaxConsecutiveConstraint

Source: https://context7.com/boristhebrave/debroglie/llms.txt

MaxConsecutiveConstraint prevents more than a given number of identical tiles appearing consecutively along specified axes. Useful for capping platform length.

```csharp
using DeBroglie.Constraints;

var platformTile = new Tile("platform");

var constraints = new ITileConstraint[]
{
    new MaxConsecutiveConstraint
    {
        Tiles    = new HashSet<Tile> { platformTile },
        MaxCount = 4,           // no run longer than 4
        Axes     = new[] { Axis.X }, // apply only horizontally
    },
};

var propagator = new TilePropagator(model, topology, constraints: constraints);
propagator.Run();
```