Skip to main content

qualia_vision/
cifar_taxonomy.rs

1//! CIFAR-10 & CIFAR-100 Taxonomy & Semantic Resolver.
2//!
3//! Provides zero-allocation FNV-1a IRI hashing, class ID lookup, supercategory mapping,
4//! and display name resolution for CIFAR-10 (10 classes) and CIFAR-100 (100 fine classes / 20 superclasses).
5
6use crate::semantic::q_hash;
7
8/// CIFAR-10 object classes (Display Name, Class Index 0..9).
9pub const CIFAR_10_CLASSES: &[(&str, u32)] = &[
10    ("airplane", 0),
11    ("automobile", 1),
12    ("bird", 2),
13    ("cat", 3),
14    ("deer", 4),
15    ("dog", 5),
16    ("frog", 6),
17    ("horse", 7),
18    ("ship", 8),
19    ("truck", 9),
20];
21
22/// CIFAR-100 fine classes (Fine Display Name, Class Index 0..99, Superclass Name).
23pub const CIFAR_100_CLASSES: &[(&str, u32, &str)] = &[
24    // 0: Aquatic mammals
25    ("beaver", 0, "aquatic_mammals"),
26    ("dolphin", 1, "aquatic_mammals"),
27    ("otter", 2, "aquatic_mammals"),
28    ("seal", 3, "aquatic_mammals"),
29    ("whale", 4, "aquatic_mammals"),
30    // 1: Fish
31    ("aquarium_fish", 5, "fish"),
32    ("flatfish", 6, "fish"),
33    ("ray", 7, "fish"),
34    ("shark", 8, "fish"),
35    ("trout", 9, "fish"),
36    // 2: Flowers
37    ("orchid", 10, "flowers"),
38    ("poppy", 11, "flowers"),
39    ("rose", 12, "flowers"),
40    ("sunflower", 13, "flowers"),
41    ("tulip", 14, "flowers"),
42    // 3: Food containers
43    ("bottle", 15, "food_containers"),
44    ("bowl", 16, "food_containers"),
45    ("can", 17, "food_containers"),
46    ("cup", 18, "food_containers"),
47    ("plate", 19, "food_containers"),
48    // 4: Fruit and vegetables
49    ("apple", 20, "fruit_and_vegetables"),
50    ("mushroom", 21, "fruit_and_vegetables"),
51    ("orange", 22, "fruit_and_vegetables"),
52    ("pear", 23, "fruit_and_vegetables"),
53    ("sweet_pepper", 24, "fruit_and_vegetables"),
54    // 5: Household electrical devices
55    ("clock", 25, "household_electrical_devices"),
56    ("keyboard", 26, "household_electrical_devices"),
57    ("lamp", 27, "household_electrical_devices"),
58    ("telephone", 28, "household_electrical_devices"),
59    ("television", 29, "household_electrical_devices"),
60    // 6: Household furniture
61    ("bed", 30, "household_furniture"),
62    ("chair", 31, "household_furniture"),
63    ("couch", 32, "household_furniture"),
64    ("table", 33, "household_furniture"),
65    ("wardrobe", 34, "household_furniture"),
66    // 7: Insects
67    ("bee", 35, "insects"),
68    ("beetle", 36, "insects"),
69    ("butterfly", 37, "insects"),
70    ("caterpillar", 38, "insects"),
71    ("cockroach", 39, "insects"),
72    // 8: Large carnivores
73    ("bear", 40, "large_carnivores"),
74    ("leopard", 41, "large_carnivores"),
75    ("lion", 42, "large_carnivores"),
76    ("tiger", 43, "large_carnivores"),
77    ("wolf", 44, "large_carnivores"),
78    // 9: Large man-made outdoor things
79    ("bridge", 45, "large_man_made_outdoor_things"),
80    ("castle", 46, "large_man_made_outdoor_things"),
81    ("house", 47, "large_man_made_outdoor_things"),
82    ("road", 48, "large_man_made_outdoor_things"),
83    ("skyscraper", 49, "large_man_made_outdoor_things"),
84    // 10: Large natural outdoor scenes
85    ("cloud", 50, "large_natural_outdoor_scenes"),
86    ("forest", 51, "large_natural_outdoor_scenes"),
87    ("mountain", 52, "large_natural_outdoor_scenes"),
88    ("plain", 53, "large_natural_outdoor_scenes"),
89    ("sea", 54, "large_natural_outdoor_scenes"),
90    // 11: Large omnivores and herbivores
91    ("camel", 55, "large_omnivores_and_herbivores"),
92    ("cattle", 56, "large_omnivores_and_herbivores"),
93    ("chimpanzee", 57, "large_omnivores_and_herbivores"),
94    ("elephant", 58, "large_omnivores_and_herbivores"),
95    ("kangaroo", 59, "large_omnivores_and_herbivores"),
96    // 12: Medium-sized mammals
97    ("fox", 60, "medium_sized_mammals"),
98    ("porcupine", 61, "medium_sized_mammals"),
99    ("possum", 62, "medium_sized_mammals"),
100    ("raccoon", 63, "medium_sized_mammals"),
101    ("skunk", 64, "medium_sized_mammals"),
102    // 13: Non-insect invertebrates
103    ("crab", 65, "non_insect_invertebrates"),
104    ("lobster", 66, "non_insect_invertebrates"),
105    ("snail", 67, "non_insect_invertebrates"),
106    ("spider", 68, "non_insect_invertebrates"),
107    ("worm", 69, "non_insect_invertebrates"),
108    // 14: People
109    ("baby", 70, "people"),
110    ("boy", 71, "people"),
111    ("girl", 72, "people"),
112    ("man", 73, "people"),
113    ("woman", 74, "people"),
114    // 15: Reptiles
115    ("crocodile", 75, "reptiles"),
116    ("dinosaur", 76, "reptiles"),
117    ("lizard", 77, "reptiles"),
118    ("snake", 78, "reptiles"),
119    ("turtle", 79, "reptiles"),
120    // 16: Small mammals
121    ("hamster", 80, "small_mammals"),
122    ("mouse", 81, "small_mammals"),
123    ("rabbit", 82, "small_mammals"),
124    ("shrew", 83, "small_mammals"),
125    ("squirrel", 84, "small_mammals"),
126    // 17: Trees
127    ("maple_tree", 85, "trees"),
128    ("oak_tree", 86, "trees"),
129    ("palm_tree", 87, "trees"),
130    ("pine_tree", 88, "trees"),
131    ("willow_tree", 89, "trees"),
132    // 18: Vehicles 1
133    ("bicycle", 90, "vehicles_1"),
134    ("bus", 91, "vehicles_1"),
135    ("motorcycle", 92, "vehicles_1"),
136    ("pickup_truck", 93, "vehicles_1"),
137    ("train", 94, "vehicles_1"),
138    // 19: Vehicles 2
139    ("lawn_mower", 95, "vehicles_2"),
140    ("rocket", 96, "vehicles_2"),
141    ("streetcar", 97, "vehicles_2"),
142    ("tank", 98, "vehicles_2"),
143    ("tractor", 99, "vehicles_2"),
144];
145
146/// Resolve a CIFAR-10 class display name by numeric class index (0..9).
147pub fn lookup_cifar10_class_by_id(id: u32) -> Option<&'static str> {
148    CIFAR_10_CLASSES
149        .iter()
150        .find(|(_, idx)| *idx == id)
151        .map(|(name, _)| *name)
152}
153
154/// Resolve a CIFAR-100 fine class display name and superclass by numeric fine class index (0..99).
155pub fn lookup_cifar100_class_by_id(id: u32) -> Option<(&'static str, &'static str)> {
156    CIFAR_100_CLASSES
157        .iter()
158        .find(|(_, idx, _)| *idx == id)
159        .map(|(name, _, superclass)| (*name, *superclass))
160}
161
162/// Resolve a CIFAR-10 or CIFAR-100 display name by its deterministic FNV-1a class hash.
163pub fn lookup_cifar_class_by_hash(class_hash: u64) -> Option<&'static str> {
164    if let Some((name, _)) = CIFAR_10_CLASSES
165        .iter()
166        .find(|(name, _)| q_hash(name) == class_hash)
167    {
168        return Some(*name);
169    }
170    if let Some((name, _, _)) = CIFAR_100_CLASSES
171        .iter()
172        .find(|(name, _, _)| q_hash(name) == class_hash)
173    {
174        return Some(*name);
175    }
176    None
177}
178
179/// Compute the deterministic 64-bit FNV-1a class hash for a CIFAR display name.
180pub fn q_hash_cifar_class(display_name: &str) -> u64 {
181    q_hash(display_name)
182}
183
184#[cfg(test)]
185mod tests {
186    use super::*;
187
188    #[test]
189    fn test_cifar_taxonomy_lookups() {
190        assert_eq!(lookup_cifar10_class_by_id(0), Some("airplane"));
191        assert_eq!(lookup_cifar10_class_by_id(3), Some("cat"));
192        assert_eq!(lookup_cifar10_class_by_id(5), Some("dog"));
193
194        let (fine, superclass) = lookup_cifar100_class_by_id(73).unwrap();
195        assert_eq!(fine, "man");
196        assert_eq!(superclass, "people");
197
198        let (dolphin, super_d) = lookup_cifar100_class_by_id(1).unwrap();
199        assert_eq!(dolphin, "dolphin");
200        assert_eq!(super_d, "aquatic_mammals");
201
202        let frog_hash = q_hash("frog");
203        assert_eq!(lookup_cifar_class_by_hash(frog_hash), Some("frog"));
204    }
205}