vox_format/lib.rs
1//! # Overview
2//!
3//! This crate provides a reader and write for [MagicaVoxel's](https://ephtracy.github.io/) VOX files. It was designed with the
4//! in mind to keep copying to a minimum. While you can read a full VOX file
5//! into a [`VoxData`] and then read or manipulate its data, there's also an
6//! interface to construct your own voxel data from a VOX file.
7//!
8//! If you're looking for a command-line utility to manipulate VOX files, take a look at [`vox-tool`](https://docs.rs/vox-tool).
9//! `vox-tool` is written using `vox-format`. so everything it does, can also be
10//! achieved using only this crate in Rust.
11//!
12//! ## Features
13//!
14//! ### `image` support
15//!
16//! This crate has support for some conversion between its types and [`image`]
17//! types. Specifically between [`crate::types::Color`] and `Rgba<u8>`. But it
18//! also provides methods to read and write palettes from images.
19//!
20//! ### `mint` and `nalgebra` support
21//!
22//! The feature [`mint`] and [`nalgebra`] enables conversion for
23//! [`crate::types::Vector`] for these crates.
24//!
25//! ### `palette` support
26//!
27//! This feature enables conversion between [`crate::types::Color`] and
28//! `Srgb<u8>` from the [`palette`] crate.
29//!
30//! ### `serialize`
31//!
32//! Enables serialization using [`serde`] for types in [`crate::types`] and
33//! [`crate::data::VoxData`].
34//!
35//! # This crate is work-in-progress
36//!
37//! Although this crate has a very limited scope and already mostly implements
38//! it, it is missing some features and isn't well-tested yet. This will change
39//! soon, but if you just can't wait, you're welcome to contribute 🥺.
40//!
41//! # Examples
42//!
43//! Reads [`crate::data::VoxData`] from path:
44//!
45//! ```rust
46//! # let path = "../test_files/test_single_model_default_palette.vox";
47//! let vox_data = vox_format::from_file(path).unwrap();
48//! println!("{:#?}", vox_data);
49//! ```
50//!
51//! [`image`]: https://docs.rs/image/0.23.14/image/index.html
52//! [`mint`]: https://docs.rs/mint/0.5.6/mint/index.html
53//! [`nalgebra`]: https://docs.rs/nalgebra/0.28.0/nalgebra/index.html
54//! [`palette`]: https://docs.rs/palette/0.6.0/palette/index.html
55
56pub mod chunk;
57pub mod data;
58pub mod default_palette;
59pub mod reader;
60pub mod types;
61pub mod writer;
62
63pub use crate::{
64 data::VoxData,
65 reader::{
66 from_file,
67 from_reader,
68 from_slice,
69 },
70 writer::{
71 to_file,
72 to_vec,
73 to_writer,
74 },
75};
76
77#[cfg(feature = "image")]
78mod image;
79
80#[cfg(feature = "palette")]
81mod palette;
82
83#[cfg(feature = "mint")]
84mod mint;
85
86#[cfg(feature = "nalgebra")]
87mod nalgebra;