1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
//! # WFC工具模块
//!
//! 本模块定义了Wave Function Collapse (WFC)系统的基础类型、错误处理和核心抽象,
//! 是对原C++ WFCutil.h的Rust重写版本。
//!
//! ## 模块概述
//!
//! 本模块包含以下核心组件:
//!
//! - **基础类型**:对应原C++的using类型别名
//! - **数据结构**:单元格、边、瓷砖等核心数据结构
//! - **错误处理**:类型安全的错误系统
//! - **方向系统**:支持方向感知的trait设计
//! - **工具函数**:常用的辅助函数
//!
//! ## 与原C++的对应关系
//!
//! | C++类型/概念 | Rust类型/概念 | 说明 |
//! |-------------|---------------|------|
//! | `CellID = Cell*` | [`CellId = NodeIndex`] | 单元格标识符 |
//! | `EdgeID = GraphEdge*` | [`EdgeId = EdgeIndex`] | 边标识符 |
//! | `TileID<EdgeData>` | [`TileId = usize`] | 瓷砖标识符 |
//! | `std::vector<CellID>` | [`Cells = Vec<CellId>`] | 单元格集合 |
//! | `Cell` class | [`Cell`] struct | 单元格数据 |
//! | `GraphEdge` class | [`GraphEdge`] struct | 边数据 |
//! | `Tile<EdgeData>` class | [`Tile<EdgeData>`] struct | 瓷砖模板 |
//!
//! ## 设计改进
//!
//! ### 1. 类型安全
//!
//! - 使用强类型别名替代原C++的指针类型
//! - 编译时类型检查,避免类型混淆
//! - 泛型设计支持不同的边数据类型
//!
//! ### 2. 内存安全
//!
//! - 自动内存管理,无需手动释放
//! - 借用检查器防止数据竞争
//! - 使用索引替代指针,避免悬垂指针
//!
//! ### 3. 错误处理
//!
//! - 使用`Result`类型进行错误处理
//! - 详细的错误分类,替代原C++的异常机制
//! - 所有可能的错误情况都有明确的类型表示
//!
//! ### 4. 方向系统
//!
//! 引入了原C++中没有的方向感知能力:
//!
//! - [`DirectionTrait`]:通用的方向抽象
//! - [`Direction4`]:四方向网格的具体实现
//! - 支持编译时方向验证和运行时方向查询
//!
//! ## 使用示例
//!
//! ### 基础类型使用
//!
//! ```rust
//! use rlwfc::{Cell, GraphEdge, Tile, Direction4, DirectionTrait};
//!
//! // 创建单元格
//! let cell = Cell::with_id(1);
//!
//! // 创建边
//! let edge = GraphEdge::with_weight(10);
//!
//! // 创建瓷砖
//! let tile = Tile::new(0, 5, vec!["A", "B", "C", "D"]);
//!
//! // 使用方向
//! let direction = Direction4::East;
//! println!("Direction: {}", direction.name());
//! ```
//!
//! ### 方向系统使用
//!
//! ```rust
//! use rlwfc::{Direction4, DirectionTrait};
//!
//! // 获取邻居索引映射
//! let east_index = Direction4::East.to_neighbor_index();
//!
//! // 获取相反方向
//! let west = Direction4::East.opposite().unwrap();
//!
//! // 枚举所有方向
//! for direction in Direction4::all_directions() {
//! println!("Direction: {}", direction.name());
//! }
//! ```
//!
//! ## petgraph集成
//!
//! 本模块设计为与petgraph图库无缝集成:
//!
//! - 使用`NodeIndex`作为单元格ID
//! - 使用`EdgeIndex`作为边ID
//! - 定义`WFCGraph`类型别名方便使用
//! - 支持有向图的方向感知功能
use ;
/**
* @file wfc_util.rs
* @author amazcuter (amazcuter@outlook.com)
* @brief WFC系统基础类型定义 - Rust重写版本
* 定义了基本概念和类型,对应原C++ WFCutil.h的功能
* @version 1.0
* @date 2025-01-25
*
* @copyright Copyright (c) 2025
*/
use ;
// =============================================================================
// 基础类型别名 - 对应原C++的using定义
// =============================================================================
/// 单元格ID,对应原C++的CellID = Cell*
///
/// 在Rust实现中,我们使用petgraph的`NodeIndex`来标识单元格,
/// 这比C++的指针类型更安全,避免了悬垂指针等内存安全问题。
pub type CellId = NodeIndex;
/// 边ID,对应原C++的EdgeID = GraphEdge*
///
/// 同样使用petgraph的`EdgeIndex`来标识边,提供类型安全的边引用。
pub type EdgeId = EdgeIndex;
/// 瓷砖ID,基于索引的实现,对应原C++的`TileID<EdgeData>`
///
/// 使用简单的usize索引来标识瓷砖,避免了C++模板的复杂性。
pub type TileId = usize;
/// 单元格集合,对应原C++的`Cells = std::vector<CellID>`
pub type Cells = ;
/// 瓷砖集合,对应原C++的`Tiles = std::vector<TileID<EdgeData>>`
pub type Tiles = ;
/// 边集合,对应原C++的`Edges = std::vector<EdgeID>`
pub type Edges = ;
/// WFC系统使用的图类型 - 使用有向图实现方向感知
///
/// 这是整个WFC系统的核心数据结构类型别名。使用有向图的原因:
///
/// 1. **方向感知**:每条边都有明确的方向性
/// 2. **稳定顺序**:petgraph保证邻居返回的稳定顺序
/// 3. **高效查询**:O(1)的邻居查询操作
pub type WFCGraph = ;
// =============================================================================
// 基础数据结构
// =============================================================================
/// 单元格数据,对应原C++的Cell类
///
/// 在petgraph架构中,单元格作为图的节点数据存储。与原C++实现不同,
/// 这里不需要存储边信息,因为连接关系完全由petgraph的图结构管理。
///
/// ## 设计优势
///
/// - **简化结构**:移除了原C++中复杂的边管理逻辑
/// - **内存效率**:只存储必要的单元格属性
/// - **类型安全**:使用Option类型处理可选字段
///
/// ## 使用示例
///
/// ```rust
/// use rlwfc::Cell;
///
/// // 创建简单单元格
/// let cell1 = Cell::new();
///
/// // 创建带ID的单元格
/// let cell2 = Cell::with_id(42);
///
/// // 创建带名称的单元格
/// let cell3 = Cell::with_name("center_cell".to_string());
/// ```
/// 图边数据,对应原C++的GraphEdge类
///
/// 在petgraph架构中,边数据存储与边关联的附加信息。与原C++实现不同,
/// 边的连接关系(from/to)完全由petgraph的图结构管理,这里只存储边的属性。
///
/// ## 设计考虑
///
/// - **权重类型**:使用整数而非浮点数,避免浮点数比较的精度问题
/// - **可选字段**:所有字段都是可选的,支持轻量级边创建
/// - **类型标识**:支持不同类型的边(如路径边、约束边等)
///
/// ## 使用场景
///
/// ```rust
/// use rlwfc::GraphEdge;
///
/// // 简单边
/// let simple_edge = GraphEdge::new();
///
/// // 带权重的边
/// let weighted_edge = GraphEdge::with_weight(10);
///
/// // 带类型的边
/// let typed_edge = GraphEdge::with_type("path".to_string());
/// ```
// =============================================================================
// 错误处理
// =============================================================================
/// 网格系统错误类型
// =============================================================================
// 方向系统
// =============================================================================
/// 方向trait - 泛型设计,适配各种网格系统
///
/// 这是WFC系统中方向感知功能的核心抽象。与原C++实现不同,
/// Rust版本引入了完整的方向系统来支持方向感知的图操作。
///
/// ## 设计理念
///
/// ### 1. 方向到索引的映射
///
/// 核心创新是利用petgraph有向图的稳定邻居顺序来实现零成本的方向识别:
///
/// - petgraph的`neighbors()`返回邻居的顺序是插入顺序的逆序
/// - 通过标准化边创建顺序,可以建立方向到索引的固定映射
/// - 这样就能通过方向名称直接获取对应的邻居
///
/// ### 2. 双向映射策略
///
/// 对于完整的双向连接(如2D网格),采用以下策略:
///
/// - **前向方向**:直接从`neighbors()`结果获取(如东、南)
/// - **反向方向**:通过反向查找获取(如西、北)
///
/// ### 3. 类型约束
///
/// 要求实现类型满足以下约束:
/// - `Clone + Copy`:值语义,便于传递
/// - `PartialEq + Eq`:支持比较操作
/// - `Hash`:支持在HashMap等容器中使用
/// - `Debug`:便于调试输出
///
/// ## 使用模式
///
/// ```rust
/// use rlwfc::{Direction4, DirectionTrait};
///
/// // 获取方向对应的邻居索引
/// if let Some(index) = Direction4::East.to_neighbor_index() {
/// // 可以直接从neighbors()[index]获取该方向的邻居
/// println!("East neighbor at index {}", index);
/// }
///
/// // 获取相反方向
/// let west = Direction4::East.opposite().unwrap();
/// assert_eq!(west, Direction4::West);
///
/// // 枚举所有方向
/// for direction in Direction4::all_directions() {
/// println!("Direction: {}", direction.name());
/// }
/// ```
///
/// ## 扩展性
///
/// 这个trait设计支持多种网格类型:
///
/// - **2D四方向**:东南西北(已实现为`Direction4`)
/// - **2D八方向**:包含对角线方向
/// - **六角形网格**:六个方向
/// - **3D网格**:包含上下方向
/// - **自定义拓扑**:任意连接模式
/// 四方向网格的标准实现
// =============================================================================
// 瓷砖系统
// =============================================================================
/// 瓷砖类,对应原C++的`Tile<EdgeData>`模板类
///
/// # ⚠️ 重要:边数据顺序约定
///
/// 瓷砖的 `edges` 字段必须严格按照网格系统 `neighbors()` 返回的顺序排列:
/// **[北, 西, 南, 东]**
///
/// ## 顺序约定的重要性
///
/// 这个顺序约定是整个WFC系统高效运行的基础:
///
/// 1. **直接索引映射**:`TileSetVirtual::judge_possibility()` 中可以直接通过索引访问对应方向的边数据
/// 2. **零成本抽象**:无需运行时的方向映射转换
/// 3. **统一语义**:网格构建顺序、neighbors()顺序、瓷砖边数据顺序完全对应
/// 4. **高效兼容性检查**:O(1) 时间复杂度的边数据访问
///
/// ## 顺序对应关系
///
/// ```text
/// 网格边创建顺序:东 → 南 → 西 → 北
/// neighbors() 返回:[北, 西, 南, 东] (petgraph 逆序特性)
/// 瓷砖边数据索引:[0, 1, 2, 3]
/// 方向到索引映射:北=0, 西=1, 南=2, 东=3
/// ```
///
/// ## 正确使用示例
///
/// ```rust
/// use rlwfc::Tile;
///
/// // ✅ 正确:按照 [北, 西, 南, 东] 顺序排列
/// let tile = Tile::new(0, 10, vec![
/// "forest", // 北边数据 (索引 0)
/// "water", // 西边数据 (索引 1)
/// "grass", // 南边数据 (索引 2)
/// "stone", // 东边数据 (索引 3)
/// ]);
///
/// // ❌ 错误:任意顺序会破坏兼容性检查
/// let wrong_tile = Tile::new(1, 5, vec![
/// "stone", // 这样的顺序无法与网格正确对应
/// "forest",
/// "water",
/// "grass",
/// ]);
/// ```
///
/// ## 在兼容性检查中的应用
///
/// ```rust,no_run
/// # use rlwfc::{Tile, TileId};
/// # let candidate_tile = Tile::new(0, 10, vec!["A", "B", "C", "D"]);
/// # let neighbor_tile = Tile::new(1, 10, vec!["D", "C", "B", "A"]);
/// # let direction_index = 0;
/// // 直接通过索引获取对应方向的边数据
/// let candidate_edge = &candidate_tile.edges[direction_index];
///
/// // 计算邻居瓷砖相对方向的索引
/// let opposite_index = match direction_index {
/// 0 => 2, // 北 ↔ 南
/// 1 => 3, // 西 ↔ 东
/// 2 => 0, // 南 ↔ 北
/// 3 => 1, // 东 ↔ 西
/// _ => panic!("无效的方向索引"),
/// };
/// let neighbor_edge = &neighbor_tile.edges[opposite_index];
///
/// // 执行兼容性检查
/// let is_compatible = candidate_edge == neighbor_edge;
/// ```
// =============================================================================
// 工具函数
// =============================================================================
/// 在二维向量中查找元素,对应原C++的findIn2DVector函数
// =============================================================================
// 测试模块
// =============================================================================