Crate modelio

Expand description

§modelio-rs

Safe Rust bindings for Apple’s ModelIO framework on macOS. The published Cargo package is modelio-rs; the Rust library target is modelio.

Status: v0.2.2 brings the SDK audit to 117/117 top-level ModelIO symbols (100%) and adds material graphs/samplers, stereoscopic cameras, area/photometric lights, object containers, matrix arrays, voxel extras, SDK constants, and USDZ conversion helpers.

§Highlights

Asset for loading, exporting, and walking ModelIO assets
Mesh for procedural primitives, vertex buffer reads, submesh inspection, and vertex descriptor access
Material, MaterialProperty, TextureFilter, TextureSampler, and material-graph wrappers for physically plausible materials, standalone properties, and sampler/graph authoring
Light, AreaLight, PhotometricLight, PhysicallyPlausibleLight, Camera, and StereoscopicCamera for scene-lighting and camera control surfaces
Object and ObjectContainer for hierarchy creation, child traversal, path lookup, and transform-component attachment
Transform, TransformStack, and typed transform ops for explicit transform authoring
MeshBufferData, MeshBufferDataAllocator, and related wrappers for buffer-authoring workflows
AssetResolver plus path, bundle, and relative resolvers for asset lookup control
VoxelArray for sparse voxel grids, asset/mesh voxelization, boolean ops, and coarse/smooth mesh generation
Texture for URL-backed textures, checkerboards, procedural gradients/noise/sky cubes, metadata, writes, and texel extraction
LightProbe and LightProbeIrradianceDataSource for probe generation and placement helpers
Skeleton, Matrix4x4Array, PackedJointAnimation, AnimationBindComponent, and animated value wrappers for rigging and animation workflows
VertexDescriptor, VertexAttribute, VertexBufferLayout, runtime SDK constant accessors, and Utility for vertex layout inspection and auxiliary SDK helpers

§Quick start

use modelio::prelude::*;

fn main() -> modelio::Result<()> {
    let mesh = Mesh::new_box([1.0, 1.0, 1.0], [1, 1, 1], false, GeometryType::Triangles)?;
    let bbox = mesh.bounding_box();

    println!("vertices={}", mesh.vertex_count());
    println!("submeshes={}", mesh.submesh_count());
    println!("bounds min={:?} max={:?}", bbox.min, bbox.max);
    Ok(())
}

§Surface overview

§Assets + objects

Asset::new, from_url, export_to_url, place_light_probes
Asset::count, object_at, object_at_path, mesh_at, meshes
Asset::frame_interval, start_time, end_time, up_axis
Object::new, name, path, hidden, add_child, child_at, at_path, transform_component, children_container
ObjectContainer::new, count, object_at, add_object
PathAssetResolver, BundleAssetResolver, RelativeAssetResolver, and AssetResolver::resolve_asset_named

§Meshes + submeshes + vertex data

Mesh::new_box, new_plane, new_ellipsoid, new_sphere, new_cylinder, new_icosahedron
Mesh::vertex_count, vertex_buffers, submeshes, bounding_box, vertex_descriptor
MeshBuffer::map, fill_data, allocator, zone, as_data_buffer
MeshBufferData, MeshBufferDataAllocator, MeshBufferZoneDefault, and MeshBufferMap
VertexAttributeData::info, bytes
Submesh::index_count, index_type, geometry_type, index_buffer, material, set_material, topology
SubmeshTopology::new, crease/index buffer accessors, and face-count mutation
VertexDescriptor::info, attributes, attribute_named, copy, layouts
VertexAttribute::new, info, set_initialization_value
VertexBufferLayout::new, stride, set_stride

§Materials + textures

Material::new, info, material_face, property_with_semantic, property_named, load_textures_using_resolver
MaterialProperty::new, info, set_float, set_color, set_string, set_url, texture, texture_sampler
TextureFilter::new, wrap/filter setters, and info
TextureSampler::new, texture/filter/transform setters, and info
MaterialPropertyConnection, MaterialPropertyNode, and MaterialPropertyGraph for graph construction/evaluation
Texture::from_url, new_checkerboard, new_color_temperature_gradient, new_color_gradient, new_vector_noise, new_scalar_noise, new_cellular_noise, new_normal_map, new_sky_cube
Texture::info, write_to_url, update_sky_cube, texel_data_top_left, texel_data_bottom_left

§Lights + cameras

Light::new, info, set_light_type, set_color_space, irradiance_at_point
AreaLight::new and PhotometricLight::new / new_with_ies_profile plus info accessors
LightProbe::new, reflective_texture, irradiance_texture, generate_spherical_harmonics_from_irradiance
LightProbeIrradianceDataSource::new, bounding_box, spherical_harmonics_level
PhysicallyPlausibleLight::new, info, set_color_temperature, set_lumens, cone-angle and attenuation setters
Camera::new, info, set_projection, set_field_of_view, look_at, look_at_from, ray_to, frame_bounding_box
StereoscopicCamera::new, info, and optical separation accessors

§Transforms + animation

Transform::new, from_component, from_matrix, translation, rotation, scale, and timed setters
TransformComponent::matrix, key_times, local_transform_at_time, global_transform_with_object
TransformStack::add_translate_op, add_rotate_*_op, add_scale_op, add_matrix_op, add_orient_op, transform_ops
TransformOp plus typed op wrappers with animated-value accessors

§Voxels + animation

VoxelArray::new, from_asset, info, set_voxel, voxel_exists, voxel_indices, voxels_within_extent
VoxelArray::set_voxels_for_mesh, union_with, intersect_with, difference_with, coarse_mesh, mesh, allocator-aware mesh extraction
Skeleton::new, info, joint_bind_transforms, joint_rest_transforms, joint_*_transform_array
Matrix4x4Array::new, info, set_float_matrices, float_matrices, clear
PackedJointAnimation::new, info, translations, rotations, scales
AnimationBindComponent::new, info, set_skeleton, set_packed_joint_animation, set_joint_paths
AnimatedScalar, AnimatedVector2/3/4, AnimatedQuaternion, AnimatedMatrix4x4
AnimatedScalarArray, AnimatedVector3Array, AnimatedQuaternionArray

§SDK helpers

ut_type::* and vertex_attribute_name::* expose ModelIO SDK NSString constants at runtime
Utility::convert_to_usdz wraps MDLUtility’s USDZ conversion helper

§Examples

The crate ships numbered examples covering every logical area:

01_primitive_smoke
02_asset_basics
03_material_properties
04_light_defaults
05_physically_plausible_light
06_camera_controls
07_object_hierarchy
08_voxel_array_boolean
09_texture_checkerboard
10_animation_bind_component
11_animated_value_types
12_submesh_material
13_vertex_attribute_descriptor
14_skeleton_basics
15_transform_stack_basics
16_mesh_buffer_allocator
17_asset_resolver_light_probe

Run one with:

cargo run --example 09_texture_checkerboard

Run them all with:

for ex in examples/*.rs; do cargo run --example "$(basename "$ex" .rs)"; done

§Tests

Integration smoke tests live under tests/ with one file per logical area plus tests/api_coverage.rs, which validates the Swift bridge against the active macOS SDK headers.

§License

Licensed under either of Apache-2.0 or MIT at your option.

Modules§

prelude: Re-exports the primary Model I/O wrappers for convenient imports.
ut_type: Groups helper APIs for the corresponding Model I/O ut type symbols.
vertex_attribute_name: Groups helper APIs for the corresponding Model I/O vertex attribute name symbols.
vertex_format: Groups helper APIs for the corresponding Model I/O vertex format symbols.

Structs§

AnimatedMatrix4x4: Wraps the corresponding Model I/O animated matrix4x4 counterpart.
AnimatedQuaternion: Wraps the corresponding Model I/O animated quaternion counterpart.
AnimatedQuaternionArray: Wraps the corresponding Model I/O animated quaternion array counterpart.
AnimatedScalar: Wraps the corresponding Model I/O animated scalar counterpart.
AnimatedScalarArray: Wraps the corresponding Model I/O animated scalar array counterpart.
AnimatedValue: Wraps the corresponding Model I/O animated value counterpart.
AnimatedValueInfo: Wraps the corresponding Model I/O animated value info counterpart.
AnimatedVector2: Wraps the corresponding Model I/O animated vector2 counterpart.
AnimatedVector3: Wraps the corresponding Model I/O animated vector3 counterpart.
AnimatedVector4: Wraps the corresponding Model I/O animated vector4 counterpart.
AnimatedVector3Array: Wraps the corresponding Model I/O animated vector3array counterpart.
AnimationBindComponent: Wraps the corresponding Model I/O animation bind component counterpart.
AreaLight: Wraps the corresponding Model I/O area light counterpart.
AreaLightInfo: Wraps the corresponding Model I/O area light info counterpart.
Asset: Wraps the corresponding Model I/O asset counterpart.
AssetInfo: Wraps the corresponding Model I/O asset info counterpart.
AssetResolver: Wraps the corresponding Model I/O asset resolver counterpart.
BoundingBox: Wraps the corresponding Model I/O bounding box counterpart.
BundleAssetResolver: Wraps the corresponding Model I/O bundle asset resolver counterpart.
Camera: Wraps the corresponding Model I/O camera counterpart.
CameraInfo: Wraps the corresponding Model I/O camera info counterpart.
Light: Wraps the corresponding Model I/O light counterpart.
LightInfo: Wraps the corresponding Model I/O light info counterpart.
LightProbe: Wraps the corresponding Model I/O light probe counterpart.
LightProbeIrradianceDataSource: Wraps the corresponding Model I/O light probe irradiance data source counterpart.
Material: Wraps the corresponding Model I/O material counterpart.
MaterialInfo: Wraps the corresponding Model I/O material info counterpart.
MaterialProperty: Wraps the corresponding Model I/O material property counterpart.
MaterialPropertyConnection: Wraps the corresponding Model I/O material property connection counterpart.
MaterialPropertyGraph: Wraps the corresponding Model I/O material property graph counterpart.
MaterialPropertyInfo: Wraps the corresponding Model I/O material property info counterpart.
MaterialPropertyNode: Wraps the corresponding Model I/O material property node counterpart.
Matrix4x4Array: Wraps the corresponding Model I/O matrix4x4array counterpart.
Matrix4x4ArrayInfo: Wraps the corresponding Model I/O matrix4x4array info counterpart.
Mesh: Wraps the corresponding Model I/O mesh counterpart.
MeshBuffer: Wraps the corresponding Model I/O mesh buffer counterpart.
MeshBufferAllocator: Wraps the corresponding Model I/O mesh buffer allocator counterpart.
MeshBufferData: Wraps the corresponding Model I/O mesh buffer data counterpart.
MeshBufferDataAllocator: Wraps the corresponding Model I/O mesh buffer data allocator counterpart.
MeshBufferInfo: Wraps the corresponding Model I/O mesh buffer info counterpart.
MeshBufferMap: Wraps the corresponding Model I/O mesh buffer map counterpart.
MeshBufferZone: Wraps the corresponding Model I/O mesh buffer zone counterpart.
MeshBufferZoneDefault: Wraps the corresponding Model I/O mesh buffer zone default counterpart.
ModelIoError: Wraps the corresponding Model I/O model io error counterpart.
Object: Wraps the corresponding Model I/O object counterpart.
ObjectContainer: Wraps the corresponding Model I/O object container counterpart.
ObjectInfo: Wraps the corresponding Model I/O object info counterpart.
PackedJointAnimation: Wraps the corresponding Model I/O packed joint animation counterpart.
PackedJointAnimationInfo: Wraps the corresponding Model I/O packed joint animation info counterpart.
PathAssetResolver: Wraps the corresponding Model I/O path asset resolver counterpart.
PhotometricLight: Wraps the corresponding Model I/O photometric light counterpart.
PhotometricLightInfo: Wraps the corresponding Model I/O photometric light info counterpart.
PhysicallyPlausibleLight: Wraps the corresponding Model I/O physically plausible light counterpart.
PhysicallyPlausibleLightInfo: Wraps the corresponding Model I/O physically plausible light info counterpart.
RelativeAssetResolver: Wraps the corresponding Model I/O relative asset resolver counterpart.
Skeleton: Wraps the corresponding Model I/O skeleton counterpart.
SkeletonInfo: Wraps the corresponding Model I/O skeleton info counterpart.
StereoscopicCamera: Wraps the corresponding Model I/O stereoscopic camera counterpart.
StereoscopicCameraInfo: Wraps the corresponding Model I/O stereoscopic camera info counterpart.
Submesh: Wraps the corresponding Model I/O submesh counterpart.
SubmeshTopology: Wraps the corresponding Model I/O submesh topology counterpart.
Texture: Wraps the corresponding Model I/O texture counterpart.
TextureFilter: Wraps the corresponding Model I/O texture filter counterpart.
TextureFilterInfo: Wraps the corresponding Model I/O texture filter info counterpart.
TextureInfo: Wraps the corresponding Model I/O texture info counterpart.
TextureSampler: Wraps the corresponding Model I/O texture sampler counterpart.
TextureSamplerInfo: Wraps the corresponding Model I/O texture sampler info counterpart.
Transform: Wraps the corresponding Model I/O transform counterpart.
TransformComponent: Wraps the corresponding Model I/O transform component counterpart.
TransformMatrixOp: Wraps the corresponding Model I/O counterpart.
TransformOp: Wraps the corresponding Model I/O transform op counterpart.
TransformOrientOp: Wraps the corresponding Model I/O counterpart.
TransformRotateOp: Wraps the corresponding Model I/O counterpart.
TransformRotateXOp: Wraps the corresponding Model I/O counterpart.
TransformRotateYOp: Wraps the corresponding Model I/O counterpart.
TransformRotateZOp: Wraps the corresponding Model I/O counterpart.
TransformScaleOp: Wraps the corresponding Model I/O counterpart.
TransformStack: Wraps the corresponding Model I/O transform stack counterpart.
TransformTranslateOp: Wraps the corresponding Model I/O counterpart.
Utility: Wraps the corresponding Model I/O utility counterpart.
VertexAttribute: Wraps the corresponding Model I/O vertex attribute counterpart.
VertexAttributeData: Wraps the corresponding Model I/O vertex attribute data counterpart.
VertexAttributeDescriptorInfo: Wraps the corresponding Model I/O vertex attribute descriptor info counterpart.
VertexAttributeInfo: Wraps the corresponding Model I/O vertex attribute info counterpart.
VertexBufferLayout: Wraps the corresponding Model I/O vertex buffer layout counterpart.
VertexDescriptor: Wraps the corresponding Model I/O vertex descriptor counterpart.
VertexDescriptorInfo: Wraps the corresponding Model I/O vertex descriptor info counterpart.
VoxelArray: Wraps the corresponding Model I/O voxel array counterpart.
VoxelArrayInfo: Wraps the corresponding Model I/O voxel array info counterpart.
VoxelIndexExtent: Wraps the corresponding Model I/O voxel index extent counterpart.

Enums§

AnimatedValueInterpolation: Mirrors the corresponding Model I/O animated value interpolation enumeration.
CameraProjection: Mirrors the corresponding Model I/O camera projection enumeration.
DataPrecision: Mirrors the corresponding Model I/O data precision enumeration.
GeometryType: Mirrors the corresponding Model I/O geometry type enumeration.
IndexBitDepth: Mirrors the corresponding Model I/O index bit depth enumeration.
LightType: Mirrors the corresponding Model I/O light type enumeration.
MaterialFace: Mirrors the corresponding Model I/O material face enumeration.
MaterialMipMapFilterMode: Mirrors the corresponding Model I/O material mip map filter mode enumeration.
MaterialPropertyType: Mirrors the corresponding Model I/O material property type enumeration.
MaterialSemantic: Mirrors the corresponding Model I/O material semantic enumeration.
MaterialTextureFilterMode: Mirrors the corresponding Model I/O material texture filter mode enumeration.
MaterialTextureWrapMode: Mirrors the corresponding Model I/O material texture wrap mode enumeration.
MeshBufferType: Mirrors the corresponding Model I/O mesh buffer type enumeration.
ObjectKind: Mirrors the corresponding Model I/O object kind enumeration.
ProbePlacement: Mirrors the corresponding Model I/O probe placement enumeration.
TextureChannelEncoding: Mirrors the corresponding Model I/O texture channel encoding enumeration.
TransformOpRotationOrder: Mirrors the corresponding Model I/O transform op rotation order enumeration.

Traits§

Component: Mirrors the corresponding Model I/O component protocol counterpart.
JointAnimation: Mirrors the corresponding Model I/O joint animation protocol counterpart.
Named: Mirrors the corresponding Model I/O named protocol counterpart.
ObjectContainerComponent: Mirrors the corresponding Model I/O object container component: component protocol counterpart.

Type Aliases§

Result: Aliases the result shape used by the corresponding Model I/O wrappers.

Crate modelio

Crate modelio Copy item path

§modelio-rs

§Highlights

§Quick start

§Surface overview

§Assets + objects

§Meshes + submeshes + vertex data

§Materials + textures

§Lights + cameras

§Transforms + animation

§Voxels + animation

§SDK helpers

§Examples

§Tests

§License

Modules§

Structs§

Enums§

Traits§

Type Aliases§

Crate modelio