added docs, updated license

Cargo.toml

@@ -2,14 +2,17 @@
 name = "c3dio"
 version = "0.1.0"
 edition = "2021"
+categories = ["encoding", "filesystem", "parser-implementation", "motion capture", "biomechanics"]
+description = "A library for reading and writing C3D files."
+license = "MIT OR Apache-2.0"
+homepage = "https://biomech.dev/c3dio"
+repository = "https://github.com/cvhammond/c3dio"
+readme = "README.md"
+keywords = ["c3d", "parser", "motion capture", "mocap", "biomechanics"]
 exclude = ["tests", "tests/*", "examples", "examples/*"]
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
 nalgebra = "0.32"
 
-[[bin]]
-name = "c3dio"
-path = "src/main.rs"
-

LICENSE → LICENSE-APACHE

@@ -174,28 +174,3 @@
       of your accepting any such warranty or additional liability.
 
    END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright [yyyy] [name of copyright owner]
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.

LICENSE-MIT

@@ -0,0 +1,19 @@
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/bytes.rs

@@ -1,4 +1,11 @@
-
+/// Bytes is a struct that contains the header, parameter, and data of a file.
+/// The header is 512 bytes long and is always the first 512 bytes of the file.
+/// The parameter data is variable length and is located after the header.
+/// The data is variable length and is located after the parameter data.
+/// The parameter data and data are stored in blocks of 512 bytes.
+///
+/// The `parameter_start_block_index` and `data_start_block_index` fields
+/// are used to calculate the byte offset of the parameter and data.
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Bytes {
     pub header: [u8; 512],

src/c3d.rs

@@ -19,6 +19,7 @@ impl PartialEq for C3d {
 }
 
 impl C3d {
+    /// Parses a C3D file from a file path.
     pub fn load(file_name: &str) -> Result<C3d, C3dParseError> {
         let c3d = C3d::new()?;
         let (c3d, mut file) = c3d.open_file(file_name)?;
@@ -29,6 +30,7 @@ impl C3d {
             .parse_data(file)?)
     }
 
+    /// Parses a C3D file from a byte slice.
     pub fn from_bytes(bytes: &[u8]) -> Result<C3d, C3dParseError> {
         let c3d = C3d::new()?
             .parse_basic_info_from_bytes(bytes)?
@@ -39,12 +41,17 @@ impl C3d {
         Ok(c3d)
     }
 
+    /// Parses a C3D file with just the header data.
     pub fn load_header(file_name: &str) -> Result<C3d, C3dParseError> {
         let c3d = C3d::new()?;
         let (c3d, mut file) = c3d.open_file(file_name)?;
         Ok(c3d.parse_basic_info(&mut file)?.parse_header()?)
     }
 
+    /// Parses a C3D file with just the header and parameter data.
+    /// The parameter data cannot be parsed without the header data.
+    /// The parameter data is parsed into a `Parameters` struct.
+    /// The `Parameters` struct can be accessed via the `parameters` field.
     pub fn load_parameters(file_name: &str) -> Result<C3d, C3dParseError> {
         let c3d = C3d::new()?;
         let (c3d, mut file) = c3d.open_file(file_name)?;
@@ -221,6 +228,9 @@ impl C3d {
     }
 }
 
+/// The steps in the process of loading and parsing a C3D file.
+/// This is used in conjunction with the `test_load_file` function
+/// to determine where a file failed to load or parse.
 #[derive(Debug, PartialEq)]
 pub enum ProcessStep {
     MakeEmpty,
@@ -232,6 +242,9 @@ pub enum ProcessStep {
     Complete,
 }
 
+/// A rudimentary test to check that a file can be loaded and parsed.
+/// This is not a comprehensive test, but it is a good first check.
+/// It is not intended to be used as a unit test.
 pub fn test_load_file(file_name: &str) -> ProcessStep {
     let c3d = match C3d::new() {
         Ok(c3d) => c3d,

src/events.rs

@@ -1,12 +1,25 @@
+/// # Events
+///
+/// Events are time points in the C3D file that are marked with a label.
+/// The label is a 4-character string that can be used to identify the event.
+/// The label is optional, and if it is not present, the event is still marked
+/// with a time point.
+/// The events are stored in the C3D file header.
+
+/// The `Events` struct contains the events from the C3D file header.
+/// Event information can be included in the parameter section of the C3D file
+/// as well, that information is stored in the `Parameter` struct.
 use crate::processor::Processor;
 use crate::C3dParseError;
 
+/// The `Events` struct contains the events from the C3D file header.
 #[derive(Debug, Clone, PartialEq)]
 pub struct Events {
     pub supports_events_labels: bool,
     events: Vec<Event>,
 }
 
+/// The `Event` struct contains the information for a single event.
 #[derive(Debug, Copy, Clone, PartialEq)]
 struct Event {
     pub label: [char; 4],

src/lib.rs

@@ -1,8 +1,21 @@
+//! # c3dio - Pure Rust C3D Parser
+//! This crate provides a parser for C3D files.
+//! C3D is a binary file format used to store motion capture data.
+//! The format is described in the [C3D file format documentation](https://www.c3d.org/HTML/default.htm).
+//!
+//! # Examples
+//! ```
+//! use c3d::prelude::*;
+//!
+//! let c3d = C3d::load("tests/data/short.c3d");
+//! assert!(c3d.is_ok());
+//! ```
+
 use std::path::PathBuf;
 use std::{error::Error, fmt};
 
 #[path = "bytes.rs"]
-pub mod bytes;
+mod bytes;
 #[path = "c3d.rs"]
 pub mod c3d;
 #[path = "data.rs"]
@@ -12,7 +25,7 @@ pub mod events;
 #[path = "parameters.rs"]
 pub mod parameters;
 #[path = "processor.rs"]
-pub mod processor;
+mod processor;
 
 use bytes::Bytes;
 use data::Data;
@@ -24,6 +37,8 @@ pub mod prelude {
     pub use crate::{parameters::ParameterData, C3d, C3dParseError};
 }
 
+/// Reports errors that occurred while parsing a C3D file.
+/// The error type is returned by the `load` and `from_bytes` methods.
 #[derive(Debug)]
 pub enum C3dParseError {
     ReadError(std::io::Error),
@@ -59,12 +74,23 @@ impl fmt::Display for C3dParseError {
     }
 }
 
+/// Represents a parsed C3D file.
+/// The file can be read from disk or from memory.
+///
+/// # Examples
+///
+/// ```
+/// use c3d::prelude::*;
+/// use std::path::PathBuf;
+/// let c3d = C3d::load(PathBuf::from("tests/data/short.c3d"));
+/// assert!(c3d.is_ok());
+/// ```
 #[derive(Debug)]
 pub struct C3d {
     pub file_path: Option<PathBuf>,
-    pub bytes: Bytes,
+    bytes: Bytes,
     pub parameters: Parameters,
-    pub processor: Processor,
+    processor: Processor,
     pub data: Data,
     pub events: Events,
 }

src/parameters.rs

@@ -4,8 +4,12 @@ use nalgebra::{DMatrix, DVector, Matrix6};
 
 use crate::processor::Processor;
 use crate::C3dParseError;
-//use ndarray::{Array, Array2, Array3, ArrayView, Ix2, Ix3, IxDyn, Order};
 
+/// The parameters of a C3D file are stored in a `Parameters` struct.
+/// Each group of parameters is stored in a separate struct.
+/// The `raw_parameters` field is a `HashMap` of `HashMap`s.
+/// The first key is the group name, and the second key is the parameter name.
+/// The value is a tuple of the parameter data and the description.
 #[derive(Debug, Clone)]
 pub struct Parameters {
     pub group_descriptions: HashMap<String, String>,
@@ -68,6 +72,7 @@ impl Parameters {
         get_signed_integer_vec(&self.raw_parameters, group, parameter)
     }
 
+    /// Returns the value of a group and parameter as a `ParameterData` enum.
     pub fn get_data(&self, group: &str, parameter: &str) -> Option<ParameterData> {
         get(&self.raw_parameters, group, parameter)
     }
@@ -1152,6 +1157,9 @@ impl TryFrom<i8> for DataType {
     }
 }
 
+/// All parameter data is stored as a vector of bytes, but the data type and dimensions of the data
+/// are also stored in the file. This struct stores the data type and dimensions, and provides
+/// methods to convert the data to a more useful format.
 #[derive(Debug, Clone, PartialEq)]
 pub enum ParameterData {
     Char(DVector<char>, Vec<usize>),