1pub const MANIFOLD_IDENTITY_V2_AXIS_ORDER: [&str; 10] =
31 ["q", "v", "w", "x", "y", "z", "t", "α", "μ", "σ"];
32
33pub const MANIFOLD_IDENTITY_V2_MAGIC: [u8; 4] = *b"MID2";
34pub const MANIFOLD_IDENTITY_V2_VERSION: u16 = 2;
35pub const MANIFOLD_IDENTITY_V2_HEADER_SIZE: usize = 112;
36pub const MANIFOLD_IDENTITY_V2_FIELD_RECORD_SIZE: usize = 48;
37pub const MANIFOLD_IDENTITY_V2_MAX_FIELDS: usize = 256;
38pub const MANIFOLD_IDENTITY_V2_MAX_BYTES: usize = MANIFOLD_IDENTITY_V2_HEADER_SIZE
39 + MANIFOLD_IDENTITY_V2_MAX_FIELDS * MANIFOLD_IDENTITY_V2_FIELD_RECORD_SIZE;
40
41const FLAG_HAS_EXTERNAL_DIGEST: u8 = 1;
42
43pub const FIELD_KIND_SCALAR: u16 = 0x0001;
44pub const FIELD_KIND_VECTOR: u16 = 0x0002;
45pub const FIELD_KIND_TENSOR: u16 = 0x0003;
46pub const FIELD_KIND_SPECTRAL: u16 = 0x0004;
47pub const FIELD_KIND_ELECTROMAGNETIC: u16 = 0x0100;
50pub const FIELD_KIND_SURFACE_FRAMES: u16 = 0x0200;
52pub const FIELD_KIND_MORPH_TARGETS: u16 = 0x0201;
55pub const FIELD_KIND_GEOMETRY_TOPOLOGY_COMPLEX: u16 = 0x0300;
57pub const BUILTIN_FIELD_KINDS: [u16; 8] = [
60 FIELD_KIND_SCALAR,
61 FIELD_KIND_VECTOR,
62 FIELD_KIND_TENSOR,
63 FIELD_KIND_SPECTRAL,
64 FIELD_KIND_ELECTROMAGNETIC,
65 FIELD_KIND_SURFACE_FRAMES,
66 FIELD_KIND_MORPH_TARGETS,
67 FIELD_KIND_GEOMETRY_TOPOLOGY_COMPLEX,
68];
69
70pub const BUILTIN_FIELD_KIND_NAMES: [(u16, &str); 8] = [
72 (FIELD_KIND_SCALAR, "scalar"),
73 (FIELD_KIND_VECTOR, "vector"),
74 (FIELD_KIND_TENSOR, "tensor"),
75 (FIELD_KIND_SPECTRAL, "spectral"),
76 (FIELD_KIND_ELECTROMAGNETIC, "electromagnetic"),
77 (FIELD_KIND_SURFACE_FRAMES, "surface_frames"),
78 (FIELD_KIND_MORPH_TARGETS, "morph_targets"),
79 (
80 FIELD_KIND_GEOMETRY_TOPOLOGY_COMPLEX,
81 "geometry_topology_complex",
82 ),
83];
84
85#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
88pub struct StableEntityId(pub [u8; 16]);
89
90#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
93pub struct IntegrityIndexDigest(pub [u8; 16]);
94
95#[derive(Debug, Clone, Copy, PartialEq)]
97pub struct ManifoldIdentityV2 {
98 pub entity_id: StableEntityId,
99 pub profile_id: u64,
101 pub domain_id: u64,
103 pub coordinate_convention_id: u64,
105 pub coordinates: [f32; 10],
107 pub external_digest: Option<IntegrityIndexDigest>,
109}
110
111impl ManifoldIdentityV2 {
112 pub fn resolves_same_entity(&self, other: &Self) -> bool {
116 self.entity_id == other.entity_id
117 }
118
119 pub fn has_same_manifold_address(&self, other: &Self) -> bool {
123 self.profile_id == other.profile_id
124 && self.domain_id == other.domain_id
125 && self.coordinate_convention_id == other.coordinate_convention_id
126 && self
127 .coordinates
128 .iter()
129 .zip(other.coordinates.iter())
130 .all(|(left, right)| left == right)
131 }
132}
133
134#[derive(Debug, Clone, Copy, PartialEq, Eq)]
138pub struct TypedFieldRecord {
139 pub field_id: u64,
141 pub kind: u16,
143 pub flags: u16,
145 pub unit_id: u64,
147 pub payload_section_id: u32,
149 pub payload_offset: u64,
151 pub payload_length: u64,
152}
153
154impl Default for TypedFieldRecord {
155 fn default() -> Self {
156 Self {
157 field_id: 0,
158 kind: 0,
159 flags: 0,
160 unit_id: 0,
161 payload_section_id: 0,
162 payload_offset: 0,
163 payload_length: 0,
164 }
165 }
166}
167
168#[derive(Debug, Clone, Copy, PartialEq, Eq)]
169pub enum ManifestV2Error {
170 TooShort { got: usize, need: usize },
171 BadMagic,
172 UnsupportedVersion(u16),
173 BadHeaderSize(u16),
174 BadTotalLength { declared: u32, actual: usize },
175 TooManyFields { got: usize, max: usize },
176 CoordinateCount(u8),
177 UnknownFlags(u8),
178 NonZeroAbsentDigest,
179 ZeroEntityId,
180 ZeroDeclarationId { field: &'static str },
181 NonFiniteCoordinate { axis: usize },
182 NonCanonicalCoordinate { axis: usize },
183 OutputTooSmall { needed: usize, have: usize },
184 InvalidFieldId,
185 InvalidFieldKind,
186 UnsupportedFieldKind(u16),
187 InvalidFieldFlags(u16),
188 FieldsNotStrictlySorted,
189 NonZeroReserved { field_index: usize },
190 InvalidPayloadReference { field_index: usize },
191 PayloadRangeOverflow { field_index: usize },
192 LengthOverflow,
193}
194
195pub fn encode_manifold_identity_v2(
199 identity: &ManifoldIdentityV2,
200 fields: &[TypedFieldRecord],
201 out: &mut [u8],
202) -> Result<usize, ManifestV2Error> {
203 encode_manifold_identity_v2_with_extensions(identity, fields, &[], out)
204}
205
206pub fn encode_manifold_identity_v2_with_extensions(
211 identity: &ManifoldIdentityV2,
212 fields: &[TypedFieldRecord],
213 supported_extension_kinds: &[u16],
214 out: &mut [u8],
215) -> Result<usize, ManifestV2Error> {
216 validate_identity(identity)?;
217 let needed = encoded_len(fields.len())?;
218 if out.len() < needed {
219 return Err(ManifestV2Error::OutputTooSmall {
220 needed,
221 have: out.len(),
222 });
223 }
224 validate_fields(fields, supported_extension_kinds)?;
225
226 let mut header = [0u8; MANIFOLD_IDENTITY_V2_HEADER_SIZE];
227 header[0..4].copy_from_slice(&MANIFOLD_IDENTITY_V2_MAGIC);
228 put_u16(&mut header, 4, MANIFOLD_IDENTITY_V2_VERSION);
229 put_u16(&mut header, 6, MANIFOLD_IDENTITY_V2_HEADER_SIZE as u16);
230 put_u32(&mut header, 8, needed as u32);
231 put_u16(&mut header, 12, fields.len() as u16);
232 header[14] = MANIFOLD_IDENTITY_V2_AXIS_ORDER.len() as u8;
233 if let Some(digest) = identity.external_digest {
234 header[15] = FLAG_HAS_EXTERNAL_DIGEST;
235 header[96..112].copy_from_slice(&digest.0);
236 }
237 header[16..32].copy_from_slice(&identity.entity_id.0);
238 put_u64(&mut header, 32, identity.profile_id);
239 put_u64(&mut header, 40, identity.domain_id);
240 put_u64(&mut header, 48, identity.coordinate_convention_id);
241 for (index, value) in identity.coordinates.iter().enumerate() {
242 put_u32(
243 &mut header,
244 56 + index * 4,
245 if *value == 0.0 { 0 } else { value.to_bits() },
246 );
247 }
248 out[..MANIFOLD_IDENTITY_V2_HEADER_SIZE].copy_from_slice(&header);
249
250 let mut offset = MANIFOLD_IDENTITY_V2_HEADER_SIZE;
251 for field in fields {
252 encode_field_record(
253 field,
254 &mut out[offset..offset + MANIFOLD_IDENTITY_V2_FIELD_RECORD_SIZE],
255 );
256 offset += MANIFOLD_IDENTITY_V2_FIELD_RECORD_SIZE;
257 }
258 Ok(needed)
259}
260
261pub fn decode_manifold_identity_v2(
265 bytes: &[u8],
266 supported_extension_kinds: &[u16],
267 out_fields: &mut [TypedFieldRecord],
268) -> Result<(ManifoldIdentityV2, usize), ManifestV2Error> {
269 if bytes.len() < MANIFOLD_IDENTITY_V2_HEADER_SIZE {
270 return Err(ManifestV2Error::TooShort {
271 got: bytes.len(),
272 need: MANIFOLD_IDENTITY_V2_HEADER_SIZE,
273 });
274 }
275 if bytes[0..4] != MANIFOLD_IDENTITY_V2_MAGIC {
276 return Err(ManifestV2Error::BadMagic);
277 }
278 let version = get_u16(bytes, 4);
279 if version != MANIFOLD_IDENTITY_V2_VERSION {
280 return Err(ManifestV2Error::UnsupportedVersion(version));
281 }
282 let header_size = get_u16(bytes, 6);
283 if header_size as usize != MANIFOLD_IDENTITY_V2_HEADER_SIZE {
284 return Err(ManifestV2Error::BadHeaderSize(header_size));
285 }
286 let declared = get_u32(bytes, 8);
287 let field_count = get_u16(bytes, 12) as usize;
288 let needed = encoded_len(field_count)?;
289 if declared as usize != bytes.len() || needed != bytes.len() {
290 return Err(ManifestV2Error::BadTotalLength {
291 declared,
292 actual: bytes.len(),
293 });
294 }
295 if bytes[14] as usize != MANIFOLD_IDENTITY_V2_AXIS_ORDER.len() {
296 return Err(ManifestV2Error::CoordinateCount(bytes[14]));
297 }
298 let flags = bytes[15];
299 if flags & !FLAG_HAS_EXTERNAL_DIGEST != 0 {
300 return Err(ManifestV2Error::UnknownFlags(flags));
301 }
302 let external_digest = if flags & FLAG_HAS_EXTERNAL_DIGEST != 0 {
303 let mut digest = [0u8; 16];
304 digest.copy_from_slice(&bytes[96..112]);
305 Some(IntegrityIndexDigest(digest))
306 } else {
307 if bytes[96..112].iter().any(|byte| *byte != 0) {
308 return Err(ManifestV2Error::NonZeroAbsentDigest);
309 }
310 None
311 };
312
313 let mut entity_bytes = [0u8; 16];
314 entity_bytes.copy_from_slice(&bytes[16..32]);
315 let mut coordinates = [0.0f32; 10];
316 for (index, coordinate) in coordinates.iter_mut().enumerate() {
317 *coordinate = f32::from_bits(get_u32(bytes, 56 + index * 4));
318 if *coordinate == 0.0 && coordinate.to_bits() != 0 {
319 return Err(ManifestV2Error::NonCanonicalCoordinate { axis: index });
320 }
321 }
322 let identity = ManifoldIdentityV2 {
323 entity_id: StableEntityId(entity_bytes),
324 profile_id: get_u64(bytes, 32),
325 domain_id: get_u64(bytes, 40),
326 coordinate_convention_id: get_u64(bytes, 48),
327 coordinates,
328 external_digest,
329 };
330 validate_identity(&identity)?;
331
332 if out_fields.len() < field_count {
333 return Err(ManifestV2Error::OutputTooSmall {
334 needed: field_count,
335 have: out_fields.len(),
336 });
337 }
338 let records = &bytes[MANIFOLD_IDENTITY_V2_HEADER_SIZE..];
339 validate_encoded_fields(records, field_count, supported_extension_kinds)?;
340 for (index, target) in out_fields.iter_mut().take(field_count).enumerate() {
341 let start = index * MANIFOLD_IDENTITY_V2_FIELD_RECORD_SIZE;
342 *target =
343 decode_field_record(&records[start..start + MANIFOLD_IDENTITY_V2_FIELD_RECORD_SIZE]);
344 }
345 Ok((identity, field_count))
346}
347
348pub fn encoded_len(field_count: usize) -> Result<usize, ManifestV2Error> {
350 if field_count > MANIFOLD_IDENTITY_V2_MAX_FIELDS {
351 return Err(ManifestV2Error::TooManyFields {
352 got: field_count,
353 max: MANIFOLD_IDENTITY_V2_MAX_FIELDS,
354 });
355 }
356 field_count
357 .checked_mul(MANIFOLD_IDENTITY_V2_FIELD_RECORD_SIZE)
358 .and_then(|n| n.checked_add(MANIFOLD_IDENTITY_V2_HEADER_SIZE))
359 .filter(|n| *n <= MANIFOLD_IDENTITY_V2_MAX_BYTES && *n <= u32::MAX as usize)
360 .ok_or(ManifestV2Error::LengthOverflow)
361}
362
363fn validate_identity(identity: &ManifoldIdentityV2) -> Result<(), ManifestV2Error> {
364 if identity.entity_id.0.iter().all(|byte| *byte == 0) {
365 return Err(ManifestV2Error::ZeroEntityId);
366 }
367 for (field, value) in [
368 ("profile_id", identity.profile_id),
369 ("domain_id", identity.domain_id),
370 (
371 "coordinate_convention_id",
372 identity.coordinate_convention_id,
373 ),
374 ] {
375 if value == 0 {
376 return Err(ManifestV2Error::ZeroDeclarationId { field });
377 }
378 }
379 for (axis, value) in identity.coordinates.iter().enumerate() {
380 if !value.is_finite() {
381 return Err(ManifestV2Error::NonFiniteCoordinate { axis });
382 }
383 }
384 Ok(())
385}
386
387fn validate_fields(
388 fields: &[TypedFieldRecord],
389 supported_extension_kinds: &[u16],
390) -> Result<(), ManifestV2Error> {
391 if fields.len() > MANIFOLD_IDENTITY_V2_MAX_FIELDS {
392 return Err(ManifestV2Error::TooManyFields {
393 got: fields.len(),
394 max: MANIFOLD_IDENTITY_V2_MAX_FIELDS,
395 });
396 }
397 let mut previous = 0u64;
398 for (index, field) in fields.iter().enumerate() {
399 if field.field_id == 0 {
400 return Err(ManifestV2Error::InvalidFieldId);
401 }
402 if index != 0 && field.field_id <= previous {
403 return Err(ManifestV2Error::FieldsNotStrictlySorted);
404 }
405 previous = field.field_id;
406 if field.kind == 0 {
407 return Err(ManifestV2Error::InvalidFieldKind);
408 }
409 if !is_known_kind(field.kind, supported_extension_kinds) {
410 return Err(ManifestV2Error::UnsupportedFieldKind(field.kind));
411 }
412 if field.flags != 0 {
413 return Err(ManifestV2Error::InvalidFieldFlags(field.flags));
414 }
415 validate_payload_reference(field, index)?;
416 }
417 Ok(())
418}
419
420fn validate_encoded_fields(
421 records: &[u8],
422 field_count: usize,
423 extensions: &[u16],
424) -> Result<(), ManifestV2Error> {
425 let mut previous = 0u64;
426 for index in 0..field_count {
427 let start = index * MANIFOLD_IDENTITY_V2_FIELD_RECORD_SIZE;
428 let record = &records[start..start + MANIFOLD_IDENTITY_V2_FIELD_RECORD_SIZE];
429 let field = decode_field_record(record);
430 if field.field_id == 0 {
431 return Err(ManifestV2Error::InvalidFieldId);
432 }
433 if index != 0 && field.field_id <= previous {
434 return Err(ManifestV2Error::FieldsNotStrictlySorted);
435 }
436 previous = field.field_id;
437 if field.kind == 0 {
438 return Err(ManifestV2Error::InvalidFieldKind);
439 }
440 if !is_known_kind(field.kind, extensions) {
441 return Err(ManifestV2Error::UnsupportedFieldKind(field.kind));
442 }
443 if field.flags != 0 {
444 return Err(ManifestV2Error::InvalidFieldFlags(field.flags));
445 }
446 if get_u32(record, 24) != 0 || get_u32(record, 44) != 0 {
447 return Err(ManifestV2Error::NonZeroReserved { field_index: index });
448 }
449 validate_payload_reference(&field, index)?;
450 }
451 Ok(())
452}
453
454fn validate_payload_reference(
455 field: &TypedFieldRecord,
456 index: usize,
457) -> Result<(), ManifestV2Error> {
458 if field.payload_section_id == 0 {
459 if field.payload_offset != 0 || field.payload_length != 0 {
460 return Err(ManifestV2Error::InvalidPayloadReference { field_index: index });
461 }
462 } else if field
463 .payload_offset
464 .checked_add(field.payload_length)
465 .is_none()
466 {
467 return Err(ManifestV2Error::PayloadRangeOverflow { field_index: index });
468 }
469 Ok(())
470}
471
472fn is_known_kind(kind: u16, extensions: &[u16]) -> bool {
473 BUILTIN_FIELD_KINDS.contains(&kind) || extensions.contains(&kind)
474}
475
476fn encode_field_record(field: &TypedFieldRecord, out: &mut [u8]) {
477 put_u64(out, 0, field.field_id);
478 put_u16(out, 8, field.kind);
479 put_u16(out, 10, field.flags);
480 put_u64(out, 12, field.unit_id);
481 put_u32(out, 20, field.payload_section_id);
482 put_u32(out, 24, 0);
483 put_u64(out, 28, field.payload_offset);
484 put_u64(out, 36, field.payload_length);
485 put_u32(out, 44, 0);
486}
487
488fn decode_field_record(bytes: &[u8]) -> TypedFieldRecord {
489 TypedFieldRecord {
490 field_id: get_u64(bytes, 0),
491 kind: get_u16(bytes, 8),
492 flags: get_u16(bytes, 10),
493 unit_id: get_u64(bytes, 12),
494 payload_section_id: get_u32(bytes, 20),
495 payload_offset: get_u64(bytes, 28),
496 payload_length: get_u64(bytes, 36),
497 }
498}
499
500fn put_u16(out: &mut [u8], offset: usize, value: u16) {
501 out[offset..offset + 2].copy_from_slice(&value.to_le_bytes());
502}
503
504fn put_u32(out: &mut [u8], offset: usize, value: u32) {
505 out[offset..offset + 4].copy_from_slice(&value.to_le_bytes());
506}
507
508fn put_u64(out: &mut [u8], offset: usize, value: u64) {
509 out[offset..offset + 8].copy_from_slice(&value.to_le_bytes());
510}
511
512fn get_u16(bytes: &[u8], offset: usize) -> u16 {
513 u16::from_le_bytes([bytes[offset], bytes[offset + 1]])
514}
515
516fn get_u32(bytes: &[u8], offset: usize) -> u32 {
517 u32::from_le_bytes([
518 bytes[offset],
519 bytes[offset + 1],
520 bytes[offset + 2],
521 bytes[offset + 3],
522 ])
523}
524
525fn get_u64(bytes: &[u8], offset: usize) -> u64 {
526 u64::from_le_bytes([
527 bytes[offset],
528 bytes[offset + 1],
529 bytes[offset + 2],
530 bytes[offset + 3],
531 bytes[offset + 4],
532 bytes[offset + 5],
533 bytes[offset + 6],
534 bytes[offset + 7],
535 ])
536}
537
538#[cfg(test)]
539#[path = "manifold_identity_v2_tests.rs"]
540mod tests;