omf/omf1/mod.rs
1//! Convert existing OMF v1 files to OMF v2.
2//!
3//! ## Conversion details
4//!
5//! There are a few parts of OMF1 that don't map directly to OMF2.
6//!
7//! ### Elements
8//!
9//! - The `date_created` and `date_modified` fields are moved into the metadata.
10//! - The `subtype` field on point-sets and line-sets is moved into the metadata.
11//! On other elements, where it only had one valid value, it is discarded.
12//! - Line-sets and surfaces with invalid vertex indices will cause conversion to fail.
13//! - Line-sets and surfaces with more than 4,294,967,295 vertices will cause conversion to fail.
14//!
15//! ### Data to Attributes
16//!
17//! - Scalar data becomes a number attribute, preserving the float/int type of the array.
18//! - In number data, NaN becomes null.
19//! - In 2D or 3D vector data, if any component is NaN the vector becomes null.
20//! - In string data, empty strings become nulls.
21//! OMF2 supports both null and empty string so we can only guess which was intended.
22//! - In date-time data, empty strings become null.
23//! - Date-times outside the range of approximately ±262,000 years CE will cause conversion to fail.
24//!
25//! ### Mapped Data to Category Attribute
26//!
27//! The exact layout of mapped data from OMF v1 can't be stored in OMF v2.
28//! It is transformed to a category attribute by following these rules:
29//!
30//! - Indices equal to minus one become null.
31//! - Indices outside the range 0 to 4,294,967,295 will cause conversion to fail.
32//! - The most unique, least empty, and shortest string legend becomes the category names,
33//! padded with empty strings if necessary.
34//! - The most unique and least empty color legend becomes the category colors, padded with
35//! gray if necessary.
36//! - Other legends become extra attributes, padded with nulls if necessary.
37
38mod array;
39mod attributes;
40mod category_handler;
41mod converter;
42mod elements;
43mod error;
44mod model;
45mod objects;
46mod reader;
47
48#[cfg(not(target_family = "wasm"))]
49pub use converter::detect_open;
50pub use converter::{Converter, detect};
51pub use error::Omf1Error;
52pub use model::ModelType;