Add UnitOffset to VoxLoaderSettings

Author: oliver-dew

examples/recentering-model.rs

@@ -0,0 +1,84 @@
+use bevy::{
+    core_pipeline::{bloom::BloomSettings, tonemapping::Tonemapping},
+    prelude::*,
+};
+use bevy_vox_scene::{UnitOffset, VoxLoaderSettings, VoxScenePlugin};
+use utilities::{PanOrbitCamera, PanOrbitCameraPlugin};
+
+fn main() {
+    App::new()
+        .add_plugins((
+            DefaultPlugins,
+            VoxScenePlugin {
+                // Using global settings because Bevy's `load_with_settings` is broken:
+                // https://github.com/bevyengine/bevy/issues/12320
+                // https://github.com/bevyengine/bevy/issues/11111
+                global_settings: Some(VoxLoaderSettings {
+                    voxel_size: 0.1,
+                    mesh_offset: UnitOffset::CENTER_BASE, // centre the model at its base
+                    ..default()
+                }),
+            },
+            PanOrbitCameraPlugin,
+        ))
+        .add_systems(Startup, setup)
+        .run();
+}
+
+fn setup(
+    mut commands: Commands,
+    assets: Res<AssetServer>,
+    mut meshes: ResMut<Assets<Mesh>>,
+    mut materials: ResMut<Assets<StandardMaterial>>,
+) {
+    commands.spawn((
+        Camera3dBundle {
+            camera: Camera {
+                hdr: true,
+                ..Default::default()
+            },
+            transform: Transform::from_xyz(8.0, 1.5, 8.0).looking_at(Vec3::ZERO, Vec3::Y),
+            tonemapping: Tonemapping::SomewhatBoringDisplayTransform,
+            ..Default::default()
+        },
+        PanOrbitCamera::default(),
+        BloomSettings {
+            intensity: 0.3,
+            ..default()
+        },
+        EnvironmentMapLight {
+            diffuse_map: assets.load("pisa_diffuse.ktx2"),
+            specular_map: assets.load("pisa_specular.ktx2"),
+            intensity: 500.0,
+        },
+        Name::new("camera"),
+    ));
+
+    commands.spawn(DirectionalLightBundle {
+        directional_light: DirectionalLight {
+            illuminance: 5000.0,
+            shadows_enabled: true,
+            ..Default::default()
+        },
+        transform: Transform::IDENTITY.looking_to(Vec3::new(2.5, -1., 0.85), Vec3::Y),
+        ..default()
+    });
+
+    commands.spawn(SceneBundle {
+        // Only load a single model when using `UnitOffset::CENTER_BASE`
+        // If you attempt to load a scene containing several models using a setting other than the default of `UnitOffset::CENTER`,
+        // their transforms will be messed up
+        scene: assets.load("study.vox#workstation/desk"),
+        ..default()
+    });
+
+    // Add a ground plane for the voxel desk to stand on
+    commands.spawn(PbrBundle {
+        mesh: meshes.add(Plane3d::new(Vec3::Y, Vec2::new(30., 30.))),
+        material: materials.add(StandardMaterial {
+            base_color: Color::LinearRgba(LinearRgba::GREEN),
+            ..default()
+        }),
+        ..default()
+    });
+}

examples/voxel-generation.rs

@@ -1,6 +1,7 @@
 use bevy::{core_pipeline::bloom::BloomSettings, prelude::*};
 use bevy_vox_scene::{
-    VoxScenePlugin, Voxel, VoxelContext, VoxelModel, VoxelModelInstance, VoxelPalette, SDF,
+    VoxLoaderSettings, VoxScenePlugin, Voxel, VoxelContext, VoxelModel, VoxelModelInstance,
+    VoxelPalette, SDF,
 };
 use utilities::{PanOrbitCamera, PanOrbitCameraPlugin};
 
@@ -46,12 +47,16 @@ fn setup(world: &mut World) {
     ]);
     let data = SDF::cuboid(Vec3::splat(13.0))
         .subtract(SDF::sphere(16.0))
-        .map_to_voxels(UVec3::splat(32), 1.0, |d, _| match d {
-            x if x < -1.0 => Voxel(2),
-            x if x < 0.0 => Voxel(1),
-            x if x >= 0.0 => Voxel::EMPTY,
-            _ => Voxel::EMPTY,
-        });
+        .map_to_voxels(
+            UVec3::splat(32),
+            VoxLoaderSettings::default(),
+            |d, _| match d {
+                x if x < -1.0 => Voxel(2),
+                x if x < 0.0 => Voxel(1),
+                x if x >= 0.0 => Voxel::EMPTY,
+                _ => Voxel::EMPTY,
+            },
+        );
     let context = VoxelContext::new(world, palette);
     let model_name = "my sdf model";
     let Some((model_handle, model)) =

src/lib.rs

@@ -59,7 +59,7 @@ mod tests;
 
 #[doc(inline)]
 use load::VoxSceneLoader;
-pub use load::{VoxLoaderSettings, VoxelLayer, VoxelModelInstance};
+pub use load::{UnitOffset, VoxLoaderSettings, VoxelLayer, VoxelModelInstance};
 #[cfg(feature = "generate_voxels")]
 pub use model::sdf::SDF;
 #[cfg(feature = "modify_voxels")]

src/load/mod.rs

@@ -7,6 +7,7 @@ use bevy::{
     asset::{io::Reader, AssetLoader, AsyncReadExt, Handle, LoadContext},
     color::LinearRgba,
     log::info,
+    math::Vec3,
     pbr::StandardMaterial,
     scene::Scene,
     utils::HashSet,
@@ -33,17 +34,18 @@ pub(super) struct VoxSceneLoader {
 }
 
 /// Settings for the VoxSceneLoader.
-#[derive(Serialize, Deserialize, Clone)]
+#[derive(Serialize, Deserialize, Clone, Debug)]
 pub struct VoxLoaderSettings {
     /// The length of each side of a single voxel. Defaults to 1.0.
     pub voxel_size: f32,
     /// Whether the outer-most faces of the model should be meshed. Defaults to true. Set this to false if the outer faces of a
     /// model will never be visible, for instance if the model id part of a 3D tileset.
     pub mesh_outer_faces: bool,
-    /// Multiplier for emissive strength. Defaults to 2.0.
+    /// Amount that the vertex positions of the mesh will be offset described as unit of their size.
+    /// Defaults to [`UnitOffset::CENTER`] the center of the model, as this is where MagicaVoxel places the origin in its world editor
+    pub mesh_offset: UnitOffset,
+    /// Multiplier for emissive strength. Defaults to 10.0.
     pub emission_strength: f32,
-    /// Defaults to `true` to more accurately reflect the colours in Magica Voxel.
-    pub uses_srgb: bool,
     /// Magica Voxel doesn't let you adjust the roughness for the default "diffuse" block type, so it can be adjusted with this setting. Defaults to 0.8.
     pub diffuse_roughness: f32,
 }
@@ -53,13 +55,30 @@ impl Default for VoxLoaderSettings {
         Self {
             voxel_size: 1.0,
             mesh_outer_faces: true,
+            mesh_offset: UnitOffset::CENTER,
             emission_strength: 10.0,
-            uses_srgb: true,
             diffuse_roughness: 0.8,
         }
     }
 }
 
+/// An offset applied to the vertex positions of the mesh expressed as a unit of the mesh's size.
+/// For a fully centered mesh, use [`UnitOffset::CENTER`]
+/// For a mesh centred around it's base, use [`UnitOffset::CENTER_BASE`]
+#[derive(Serialize, Deserialize, Clone, Debug)]
+pub struct UnitOffset(pub(crate) Vec3);
+
+impl UnitOffset {
+    /// Vertex positions will not be offset at all, so that the origin will be the minimum of the model's AABB
+    pub const ZERO: Self = UnitOffset(Vec3::ZERO);
+
+    /// Offset representing the center of a model
+    pub const CENTER: Self = UnitOffset(Vec3::splat(0.5));
+
+    /// Offset representing the center base of a model
+    pub const CENTER_BASE: Self = UnitOffset(Vec3::new(0.5, 0.0, 0.5));
+}
+
 #[derive(Error, Debug)]
 pub enum VoxLoaderError {
     #[error(transparent)]
@@ -160,8 +179,7 @@ impl VoxSceneLoader {
             .enumerate()
             .for_each(|(index, (maybe_name, model))| {
                 let name = maybe_name.clone().unwrap_or(format!("model-{}", index));
-                let data =
-                    VoxelData::from_model(&model, settings.mesh_outer_faces, settings.voxel_size);
+                let data = VoxelData::from_model(&model, settings.clone());
                 let (visible_voxels, ior) = data.visible_voxels(&indices_of_refraction);
                 let mesh = load_context.labeled_asset_scope(format!("{}@mesh", name), |_| {
                     crate::model::mesh::mesh_model(&visible_voxels, &data)

src/load/parse_model.rs

@@ -3,13 +3,14 @@ use dot_vox::Model;
 
 use crate::model::{RawVoxel, VoxelData};
 
+use super::VoxLoaderSettings;
+
 impl VoxelData {
     /// Ingest Magica Voxel data and perform coordinate conversion from MV's left-handed Z-up to bevy's right-handed Y-up
-    pub(super) fn from_model(model: &Model, mesh_outer_faces: bool, voxel_size: f32) -> VoxelData {
+    pub(super) fn from_model(model: &Model, settings: VoxLoaderSettings) -> VoxelData {
         let mut data = VoxelData::new(
             UVec3::new(model.size.x, model.size.z, model.size.y),
-            mesh_outer_faces,
-            voxel_size,
+            settings,
         );
         model.voxels.iter().for_each(|voxel| {
             let raw_voxel = RawVoxel(voxel.i);

src/model/data.rs

@@ -6,24 +6,24 @@ use block_mesh::VoxelVisibility;
 use ndshape::{RuntimeShape, Shape};
 use std::fmt::Debug;
 
+use crate::VoxLoaderSettings;
+
 use super::{voxel::VisibleVoxel, RawVoxel};
 
 /// The voxel data used to create a mesh and a material.
 #[derive(Clone)]
 pub struct VoxelData {
     pub(crate) shape: RuntimeShape<u32, 3>,
     pub(crate) voxels: Vec<RawVoxel>,
-    pub(crate) mesh_outer_faces: bool,
-    pub(crate) voxel_size: f32,
+    pub(crate) settings: VoxLoaderSettings,
 }
 
 impl Default for VoxelData {
     fn default() -> Self {
         Self {
             shape: RuntimeShape::<u32, 3>::new([0, 0, 0]),
             voxels: Default::default(),
-            mesh_outer_faces: true,
-            voxel_size: 1.0,
+            settings: VoxLoaderSettings::default(),
         }
     }
 }
@@ -33,15 +33,15 @@ impl Debug for VoxelData {
         f.debug_struct("VoxelData")
             .field("shape", &self.shape.as_array())
             .field("voxels", &self.voxels.len())
-            .field("mesh_outer_faces", &self.mesh_outer_faces)
+            .field("settings", &self.settings)
             .finish()
     }
 }
 
 impl VoxelData {
     /// Returns a new, empty VoxelData model
-    pub fn new(size: UVec3, mesh_outer_faces: bool, voxel_size: f32) -> Self {
-        let padding = if mesh_outer_faces {
+    pub fn new(size: UVec3, settings: VoxLoaderSettings) -> Self {
+        let padding = if settings.mesh_outer_faces {
             UVec3::splat(2)
         } else {
             UVec3::ZERO
@@ -51,8 +51,7 @@ impl VoxelData {
         Self {
             shape,
             voxels: vec![RawVoxel::EMPTY; size],
-            mesh_outer_faces,
-            voxel_size,
+            settings,
         }
     }
     /// The size of the voxel model, not including the padding that may have been added if the outer faces are being meshed.
@@ -64,7 +63,7 @@ impl VoxelData {
 
     /// If the outer faces are to be meshed, the mesher requires 1 voxel of padding around the edge of the model
     pub(crate) fn padding(&self) -> u32 {
-        if self.mesh_outer_faces {
+        if self.settings.mesh_outer_faces {
             2
         } else {
             0

src/model/mesh.rs

@@ -22,9 +22,9 @@ pub(crate) fn mesh_model(voxels: &[VisibleVoxel], data: &VoxelData) -> Mesh {
         &quads_config.faces,
         &mut greedy_quads_buffer,
     );
-    let half_extents = data.model_size() * 0.5; // center the mesh
-    let leading_padding = (data.padding() / 2) as f32 * data.voxel_size; // corrects the 1 offset introduced by the meshing.
-    let position_offset = half_extents + Vec3::splat(leading_padding);
+    let offset = data.model_size() * data.settings.mesh_offset.0; // center the mesh
+    let leading_padding = (data.padding() / 2) as f32 * data.settings.voxel_size; // corrects the 1 offset introduced by the meshing.
+    let position_offset = offset + Vec3::splat(leading_padding);
 
     let num_indices = greedy_quads_buffer.quads.num_quads() * 6;
     let num_vertices = greedy_quads_buffer.quads.num_quads() * 4;
@@ -48,15 +48,17 @@ pub(crate) fn mesh_model(voxels: &[VisibleVoxel], data: &VoxelData) -> Mesh {
         for quad in group.iter() {
             let palette_index = voxels[data.shape.linearize(quad.minimum) as usize].index;
             indices.extend_from_slice(&face.quad_mesh_indices(positions.len() as u32));
-            positions.extend_from_slice(&face.quad_mesh_positions(quad, data.voxel_size).map(
-                |position| {
-                    [
-                        position[0] - position_offset.x,
-                        position[1] - position_offset.y,
-                        position[2] - position_offset.z,
-                    ]
-                },
-            ));
+            positions.extend_from_slice(
+                &face
+                    .quad_mesh_positions(quad, data.settings.voxel_size)
+                    .map(|position| {
+                        [
+                            position[0] - position_offset.x,
+                            position[1] - position_offset.y,
+                            position[2] - position_offset.z,
+                        ]
+                    }),
+            );
             let u = ((palette_index % 16) as f32 + 0.5) / 16.0;
             let v = ((palette_index / 16) as f32 + 0.5) / 16.0;
             uvs.extend_from_slice(&[[u, v], [u, v], [u, v], [u, v]]);

src/model/queryable.rs

@@ -100,18 +100,18 @@ impl VoxelQueryable for VoxelData {
     }
 
     fn model_size(&self) -> Vec3 {
-        self._size().as_vec3() * self.voxel_size
+        self._size().as_vec3() * self.settings.voxel_size
     }
 
     fn local_point_to_voxel_space(&self, local_point: Vec3) -> IVec3 {
         let half_extents = self.size().as_vec3() * 0.5;
-        let voxel_postition = (local_point / self.voxel_size) + half_extents;
+        let voxel_postition = (local_point / self.settings.voxel_size) + half_extents;
         voxel_postition.as_ivec3()
     }
 
     fn voxel_coord_to_local_space(&self, voxel_coord: IVec3) -> Vec3 {
         let half_extents = self.size().as_vec3() * 0.5;
-        (voxel_coord.as_vec3() - half_extents) * self.voxel_size
+        (voxel_coord.as_vec3() - half_extents) * self.settings.voxel_size
     }
 
     fn get_voxel_at_point(&self, position: IVec3) -> Result<Voxel, OutOfBoundsError> {

src/model/sdf.rs

@@ -1,6 +1,6 @@
 use bevy::math::{Quat, UVec3, Vec3};
 
-use crate::{Voxel, VoxelData};
+use crate::{VoxLoaderSettings, Voxel, VoxelData};
 
 /// A 3d signed distance field
 pub struct SDF {
@@ -72,10 +72,10 @@ impl SDF {
     pub fn map_to_voxels<F: Fn(f32, Vec3) -> Voxel>(
         self,
         size: UVec3,
-        voxel_size: f32,
+        settings: VoxLoaderSettings,
         map: F,
     ) -> VoxelData {
-        let mut data = VoxelData::new(size, true, voxel_size);
+        let mut data = VoxelData::new(size, settings);
         let half_extent = Vec3::new(size.x as f32, size.y as f32, size.z as f32) * 0.5;
         for x in 0..size.x {
             for y in 0..size.y {
@@ -92,8 +92,8 @@ impl SDF {
     }
 
     /// Converts the SDF to [`VoxelData`] by filling every cell that is less than 0 with `fill`.
-    pub fn voxelize(self, size: UVec3, voxel_size: f32, fill: Voxel) -> VoxelData {
-        self.map_to_voxels(size, voxel_size, |distance, _| {
+    pub fn voxelize(self, size: UVec3, settings: VoxLoaderSettings, fill: Voxel) -> VoxelData {
+        self.map_to_voxels(size, settings, |distance, _| {
             if distance < 0.0 {
                 fill.clone()
             } else {