differt-core 0.10.0__tar.gz → 0.12.0__tar.gz

{differt_core-0.10.0 → differt_core-0.12.0}/Cargo.lock

@@ -247,7 +247,7 @@ checksum = "43da5946c66ffcc7745f48db692ffbb10a83bfe0afd96235c5c2a4fb23994929"
 
 [[package]]
 name = "differt-core"
-version = "0.10.0"
+version = "0.12.0"
 dependencies = [
  "criterion",
  "indexmap",
@@ -262,6 +262,7 @@ dependencies = [
  "quick-xml",
  "rstest",
  "serde",
+ "tempfile",
  "testing_logger",
 ]
 

{differt_core-0.10.0 → differt_core-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: differt-core
-Version: 0.10.0
+Version: 0.12.0
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12

{differt_core-0.10.0 → differt_core-0.12.0}/differt-core/Cargo.toml

@@ -19,6 +19,7 @@ serde = {version = "1.0", features = ["derive"]}
 criterion = "0.5.1"
 pyo3 = {version = "0.25", features = ["auto-initialize"]}
 rstest = "0.18.2"
+tempfile = "3.20"
 testing_logger = "0.1.1"
 
 [features]
@@ -37,5 +38,5 @@ unexpected_cfgs = {level = "warn", check-cfg = ['cfg(tarpaulin_include)']}
 edition = "2021"
 name = "differt-core"
 rust-version = "1.78.0"
-version = "0.10.0"
+version = "0.12.0"
 readme = "README.md"

{differt_core-0.10.0 → differt_core-0.12.0}/differt-core/src/geometry/graph.rs

@@ -1,5 +1,3 @@
-#![allow(unknown_lints, non_local_definitions)]
-
 use std::collections::VecDeque;
 
 use numpy::{
@@ -156,7 +154,7 @@ pub mod complete {
         ///
         ///     Therefore, those iterators are equivalents:
         ///
-        ///     >>> from differt_core.rt import CompleteGraph, DiGraph
+        ///     >>> from differt_core.geometry import CompleteGraph, DiGraph
         ///     >>>
         ///     >>> num_nodes, depth = 100, 5
         ///     >>> complete_graph = CompleteGraph(num_nodes)

{differt_core-0.10.0 → differt_core-0.12.0}/differt-core/src/geometry/mesh.rs

@@ -1,4 +1,8 @@
-use std::{fs::File, io::BufReader, path::PathBuf};
+use std::{
+    fs::File,
+    io::BufReader,
+    path::{Path, PathBuf},
+};
 
 use indexmap::IndexMap;
 use numpy::{PyArray1, PyArray2, ndarray::arr2};
@@ -207,7 +211,14 @@ impl Mesh {
                 other.set_face_material(None);
             },
             (None, Some(_)) => {
+                // 'self' has no material of its own yet: fill placeholder (-1)
+                // entries for its existing triangles (same as the 'None' arm
+                // of 'set_face_material'), then adopt 'other's material names
+                // outright, since 'self' had none. 'other's existing
+                // face-material indices already correctly reference the
+                // just-adopted names, so they need no remapping.
                 self.set_face_material(None);
+                self.material_names = std::mem::take(&mut other.material_names);
             },
             (Some(_), Some(_)) => {
                 // We need to possibly renumber material indices.
@@ -273,22 +284,48 @@ impl Mesh {
     /// vertices.
     ///
     /// Args:
-    ///     file (str): The path to the Wavefront .obj file.
+    ///     file (str | os.PathLike[str]): The path to the Wavefront .obj file.
     ///
     /// Returns:
     ///     Mesh: The corresponding mesh containing only triangles.
     #[classmethod]
-    pub(crate) fn load_obj(_: &Bound<'_, PyType>, filename: &str) -> PyResult<Self> {
-        let input = BufReader::new(File::open(filename)?);
+    #[pyo3(name = "load_obj")]
+    pub(crate) fn py_load_obj(_: &Bound<'_, PyType>, file: PathBuf) -> PyResult<Self> {
+        Self::load_obj(&file)
+    }
+
+    /// Load a triangle mesh from a Stanford PLY .ply file.
+    ///
+    /// Currently, only vertices and triangles are loaded. Triangle normals
+    /// are ignored because they are computed with
+    /// :attr:`differt.geometry.Mesh.normals` using
+    /// JAX so that they can be differentiated with respect to triangle
+    /// vertices.
+    ///
+    /// Args:
+    ///     file (str | os.PathLike[str]): The path to the Stanford PLY .ply file.
+    ///
+    /// Returns:
+    ///     Mesh: The corresponding mesh containing only triangles.
+    #[classmethod]
+    #[pyo3(name = "load_ply")]
+    pub(crate) fn py_load_ply(_: &Bound<'_, PyType>, file: PathBuf) -> PyResult<Self> {
+        Self::load_ply(&file)
+    }
+}
+
+impl Mesh {
+    pub(crate) fn load_obj(file: &Path) -> PyResult<Self> {
+        let input = BufReader::new(File::open(file)?);
         let mut obj: RawObj = parse_obj(input).map_err(|err| {
             PyValueError::new_err(format!(
-                "An error occurred while reading obj file {filename:#?}: {}",
+                "An error occurred while reading obj file {file:#?}: {}",
                 err
             ))
         })?;
 
         for material_file in obj.material_libraries.iter_mut() {
-            let mut path = PathBuf::from(filename);
+            let mut path = file.to_path_buf();
             path.set_file_name(&material_file);
             if let Some(path_str) = path.to_str() {
                 *material_file = path_str.to_string();
@@ -298,29 +335,15 @@ impl Mesh {
         Ok(obj.into())
     }
 
-    /// Load a triangle mesh from a Stanford PLY .ply file.
-    ///
-    /// Currently, only vertices and triangles are loaded. Triangle normals
-    /// are ignored because they are computed with
-    /// :attr:`differt.geometry.Mesh.normals` using
-    /// JAX so that they can be differentiated with respect to triangle
-    /// vertices.
-    ///
-    /// Args:
-    ///     file (str): The path to the Stanford PLY .ply file.
-    ///
-    /// Returns:
-    ///     Mesh: The corresponding mesh containing only triangles.
-    #[classmethod]
-    pub(crate) fn load_ply(_: &Bound<'_, PyType>, filename: &str) -> PyResult<Self> {
-        let mut input = BufReader::new(File::open(filename)?);
+    pub(crate) fn load_ply(file: &Path) -> PyResult<Self> {
+        let mut input = BufReader::new(File::open(file)?);
 
         let vertex_parser = parser::Parser::<PlyVertex>::new();
         let face_parser = parser::Parser::<PlyFace>::new();
 
         let header = vertex_parser.read_header(&mut input).map_err(|err| {
             PyValueError::new_err(format!(
-                "An error occurred while reading the header of ply file {filename:#?}: {}",
+                "An error occurred while reading the header of ply file {file:#?}: {}",
                 err
             ))
         })?;
@@ -337,7 +360,7 @@ impl Mesh {
                             .map_err(|err| {
                                 PyValueError::new_err(format!(
                                     "An error occurred while reading the vertex elements of ply \
-                                     file {filename:#?}: {}",
+                                     file {file:#?}: {}",
                                     err
                                 ))
                             })?
@@ -352,7 +375,7 @@ impl Mesh {
                             .map_err(|err| {
                                 PyValueError::new_err(format!(
                                     "An error occurred while reading the face elements of PLY \
-                                     file {filename:#?}: {}",
+                                     file {file:#?}: {}",
                                     err
                                 ))
                             })?
@@ -507,3 +530,49 @@ pub(crate) fn mesh(m: Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<Mesh>()?;
     Ok(())
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn append_backfills_placeholder_materials_and_adopts_other_material_names() {
+        // 'self' has no material info at all yet (no `set_face_material`
+        // call was ever made on it), while 'other' already has its single
+        // triangle assigned to material "foo".
+        let mut self_mesh = Mesh {
+            vertices: vec![[0.0, 0.0, 0.0], [1.0, 0.0, 0.0], [0.0, 1.0, 0.0]],
+            triangles: vec![[0, 1, 2]],
+            ..Default::default()
+        };
+        assert!(self_mesh.face_materials.is_none());
+        assert!(self_mesh.material_names.is_empty());
+
+        let mut other_mesh = Mesh {
+            vertices: vec![[0.0, 0.0, 1.0], [1.0, 0.0, 1.0], [0.0, 1.0, 1.0]],
+            triangles: vec![[0, 1, 2]],
+            ..Default::default()
+        };
+        other_mesh.set_face_material(Some("foo".to_string()));
+
+        let other_material_names = other_mesh.material_names.clone();
+        assert_eq!(other_material_names, vec!["foo".to_string()]);
+
+        self_mesh.append(&mut other_mesh);
+
+        // 'self' adopted 'other's material names outright (moved via
+        // `std::mem::take`), since it previously had none of its own.
+        assert_eq!(self_mesh.material_names, other_material_names);
+        // 'other's material names were moved out, leaving it empty.
+        assert!(other_mesh.material_names.is_empty());
+
+        // 'self' now has face materials for both its own triangle
+        // (backfilled with the -1 placeholder) and 'other's triangle
+        // (unchanged, index 0, i.e., "foo").
+        let face_materials = self_mesh
+            .face_materials
+            .expect("face materials should be set after append");
+        assert_eq!(face_materials, vec![-1, 0]);
+        assert_eq!(self_mesh.triangles.len(), 2);
+    }
+}

differt_core-0.12.0/differt-core/src/geometry/scene.rs

@@ -0,0 +1,361 @@
+use std::{
+    collections::{HashMap, HashSet},
+    path::{Path, PathBuf},
+};
+
+use pyo3::{exceptions::PyValueError, prelude::*, types::PyType};
+
+use super::sionna::SionnaScene;
+use crate::geometry::mesh::Mesh;
+
+/// Return the set of material names for which at least two materials
+/// (i.e., two distinct XML ids) share that name but disagree on
+/// `thickness`, meaning that name alone is not enough to tell them apart.
+fn non_uniform_material_names(sionna: &SionnaScene) -> HashSet<String> {
+    let mut seen: HashMap<&str, Option<f32>> = HashMap::new();
+    let mut non_uniform = HashSet::new();
+
+    for mat in sionna.materials.values() {
+        match seen.get(mat.name.as_str()) {
+            Some(thickness) if *thickness != mat.thickness => {
+                non_uniform.insert(mat.name.clone());
+            },
+            Some(_) => {},
+            None => {
+                seen.insert(&mat.name, mat.thickness);
+            },
+        }
+    }
+
+    non_uniform
+}
+
+/// A scene that contains one mesh, usually being the results of multiple call to :meth:`Mesh.append<differt_core.geometry.Mesh.append>`.
+///
+/// This class is only useful to provide a fast constructor for scenes
+/// created using the Sionna file format.
+#[derive(Clone)]
+#[pyclass(subclass)]
+struct Scene {
+    /// differt_core.geometry.Mesh: The scene mesh.
+    #[pyo3(get)]
+    mesh: Mesh,
+}
+
+#[pymethods]
+impl Scene {
+    /// Load a scene from a Sionna-compatible XML file.
+    ///
+    /// Args:
+    ///     file (str | os.PathLike[str]): The path to the XML file.
+    ///
+    /// Returns:
+    ///     Scene: The corresponding scene.
+    #[classmethod]
+    #[pyo3(name = "load_xml")]
+    fn py_load_xml(_cls: &Bound<'_, PyType>, file: PathBuf) -> PyResult<Self> {
+        Self::load_xml(&file)
+    }
+}
+impl Scene {
+    fn load_xml(file: &Path) -> PyResult<Self> {
+        let sionna = SionnaScene::load_xml(file)?;
+
+        let folder = file.parent().ok_or_else(|| {
+            PyValueError::new_err(format!(
+                "Could not determine parent folder of file: {file:#?}",
+            ))
+        })?;
+
+        let non_uniform_names = non_uniform_material_names(&sionna);
+
+        let mut mesh = Mesh::default();
+
+        for (_, shape) in sionna.shapes.into_iter() {
+            let mesh_file_path = folder.join(shape.file);
+            let mut other_mesh = match shape.r#type.as_str() {
+                "obj" => Mesh::load_obj(&mesh_file_path)?,
+                "ply" => Mesh::load_ply(&mesh_file_path)?,
+                ty => {
+                    log::warn!("Unsupported shape type {ty}, skipping.");
+                    continue;
+                },
+            };
+
+            let material = sionna.materials.get(&shape.material_id);
+
+            let color = material.map(|mat| mat.color);
+
+            // Materials whose name is shared by another, differently
+            // configured material (currently, only 'thickness' can differ)
+            // are kept under their unique XML id, so the two remain
+            // distinguishable; every other material still shares the
+            // generic, ITU-type-derived name, matching the previous
+            // behavior (and keeping it resolvable against the built-in ITU
+            // materials database, e.g. via `differt.em.materials_from_sionna`).
+            // A material with no 'thickness' override of its own is never
+            // renamed, even if its name collides with a differently
+            // configured one: 'differt.em._material._populate_materials'
+            // only ever creates a distinct, id-keyed entry for a material
+            // that actually carries a 'thickness' (see its own leading
+            // 'if mat.thickness is None: continue'), so keying a
+            // thickness-less shape by id here would leave it without any
+            // matching entry in the Python-side materials mapping.
+            let material_name = material.map(|mat| {
+                if mat.thickness.is_some() && non_uniform_names.contains(&mat.name) {
+                    mat.id.clone()
+                } else {
+                    mat.name.clone()
+                }
+            });
+
+            other_mesh.set_face_color(color.as_ref());
+            other_mesh.set_face_material(material_name);
+
+            mesh.append(&mut other_mesh);
+        }
+        Ok(Self { mesh })
+    }
+}
+
+#[cfg(not(tarpaulin_include))]
+#[pymodule(gil_used = false)]
+pub(crate) fn scene(m: Bound<'_, PyModule>) -> PyResult<()> {
+    m.add_class::<Scene>()?;
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use std::fs;
+
+    use indexmap::IndexMap;
+    use pyo3::Python;
+    use tempfile::tempdir;
+
+    use super::*;
+    use crate::geometry::sionna::Material;
+
+    const TRIANGLE_OBJ: &str = "v 0.0 0.0 0.0\nv 1.0 0.0 0.0\nv 0.0 1.0 0.0\nf 1 2 3\n";
+
+    fn shape_xml(id: &str) -> String {
+        format!(
+            r#"
+            <shape type="obj" id="shape-{id}">
+                <string name="filename" value="mesh.obj"/>
+                <ref id="{id}"/>
+            </shape>
+            "#
+        )
+    }
+
+    #[test]
+    fn non_uniform_material_names_flags_same_name_different_thickness() {
+        let mut materials = IndexMap::new();
+        materials.insert(
+            "window1".to_string(),
+            Material {
+                name: "itu_glass".to_string(),
+                id: "window1".to_string(),
+                color: [0.168, 0.139, 0.509],
+                thickness: Some(0.01),
+            },
+        );
+        materials.insert(
+            "window2".to_string(),
+            Material {
+                name: "itu_glass".to_string(),
+                id: "window2".to_string(),
+                color: [0.168, 0.139, 0.509],
+                thickness: Some(0.05),
+            },
+        );
+        materials.insert(
+            "wall".to_string(),
+            Material {
+                name: "itu_concrete".to_string(),
+                id: "wall".to_string(),
+                color: [0.539, 0.539, 0.539],
+                thickness: None,
+            },
+        );
+        materials.insert(
+            "wall2".to_string(),
+            Material {
+                name: "itu_concrete".to_string(),
+                id: "wall2".to_string(),
+                color: [0.539, 0.539, 0.539],
+                thickness: None,
+            },
+        );
+
+        let sionna = SionnaScene {
+            materials,
+            shapes: IndexMap::new(),
+        };
+
+        let non_uniform = non_uniform_material_names(&sionna);
+
+        // Both "itu_glass" materials share a name but disagree on
+        // thickness, so the name alone cannot distinguish them.
+        assert!(non_uniform.contains("itu_glass"));
+        // Both "itu_concrete" materials agree (neither has a thickness
+        // override), so their shared name remains sufficient.
+        assert!(!non_uniform.contains("itu_concrete"));
+    }
+
+    #[test]
+    fn load_xml_keeps_ids_distinguishable_when_material_names_collide() {
+        let dir = tempdir().expect("failed to create temporary directory");
+
+        fs::write(dir.path().join("mesh.obj"), TRIANGLE_OBJ).expect("failed to write obj file");
+
+        let xml = format!(
+            r#"<scene version="2.1.0">
+                <bsdf type="itu-radio-material" id="window1">
+                    <string name="type" value="glass"/>
+                    <float name="thickness" value="0.01"/>
+                </bsdf>
+                <bsdf type="itu-radio-material" id="window2">
+                    <string name="type" value="glass"/>
+                    <float name="thickness" value="0.05"/>
+                </bsdf>
+                {}{}
+            </scene>"#,
+            shape_xml("window1"),
+            shape_xml("window2"),
+        );
+
+        let scene_file = dir.path().join("scene.xml");
+        fs::write(&scene_file, xml).expect("failed to write scene file");
+
+        let material_names: Vec<String> = Python::with_gil(|py| {
+            let scene = Scene::load_xml(&scene_file).expect("scene should load");
+            let py_scene =
+                Bound::new(py, scene).expect("failed to wrap the scene in a Python object");
+            let py_mesh = py_scene
+                .getattr("mesh")
+                .expect("scene should have a `mesh` attribute");
+            py_mesh
+                .getattr("material_names")
+                .expect("mesh should have a `material_names` attribute")
+                .extract()
+                .expect("`material_names` should be extractable as Vec<String>")
+        });
+
+        // Since the two "glass" materials disagree on thickness, they must
+        // remain distinguishable under their own XML ids, rather than both
+        // collapsing to the generic "itu_glass" name (which would make them
+        // indistinguishable from one another).
+        assert_eq!(
+            material_names,
+            vec!["window1".to_string(), "window2".to_string()]
+        );
+    }
+
+    #[test]
+    fn load_xml_keeps_generic_name_when_no_collision() {
+        let dir = tempdir().expect("failed to create temporary directory");
+
+        fs::write(dir.path().join("mesh.obj"), TRIANGLE_OBJ).expect("failed to write obj file");
+
+        let xml = format!(
+            r#"<scene version="2.1.0">
+                <bsdf type="itu-radio-material" id="window">
+                    <string name="type" value="glass"/>
+                    <float name="thickness" value="0.01"/>
+                </bsdf>
+                <bsdf type="itu-radio-material" id="wall">
+                    <string name="type" value="concrete"/>
+                </bsdf>
+                {}{}
+            </scene>"#,
+            shape_xml("window"),
+            shape_xml("wall"),
+        );
+
+        let scene_file = dir.path().join("scene.xml");
+        fs::write(&scene_file, xml).expect("failed to write scene file");
+
+        let material_names: Vec<String> = Python::with_gil(|py| {
+            let scene = Scene::load_xml(&scene_file).expect("scene should load");
+            let py_scene =
+                Bound::new(py, scene).expect("failed to wrap the scene in a Python object");
+            let py_mesh = py_scene
+                .getattr("mesh")
+                .expect("scene should have a `mesh` attribute");
+            py_mesh
+                .getattr("material_names")
+                .expect("mesh should have a `material_names` attribute")
+                .extract()
+                .expect("`material_names` should be extractable as Vec<String>")
+        });
+
+        // Neither material name collides with another, so both keep their
+        // generic, ITU-type-derived name (resolvable against the built-in
+        // ITU materials database), rather than being keyed by XML id.
+        assert_eq!(
+            material_names,
+            vec!["itu_glass".to_string(), "itu_concrete".to_string()]
+        );
+    }
+
+    #[test]
+    fn load_xml_keeps_generic_name_for_thickness_less_material_despite_collision() {
+        let dir = tempdir().expect("failed to create temporary directory");
+
+        fs::write(dir.path().join("mesh.obj"), TRIANGLE_OBJ).expect("failed to write obj file");
+
+        let xml = format!(
+            r#"<scene version="2.1.0">
+                <bsdf type="itu-radio-material" id="window1">
+                    <string name="type" value="glass"/>
+                    <float name="thickness" value="0.01"/>
+                </bsdf>
+                <bsdf type="itu-radio-material" id="window2">
+                    <string name="type" value="glass"/>
+                    <float name="thickness" value="0.05"/>
+                </bsdf>
+                <bsdf type="itu-radio-material" id="window3">
+                    <string name="type" value="glass"/>
+                </bsdf>
+                {}{}{}
+            </scene>"#,
+            shape_xml("window1"),
+            shape_xml("window2"),
+            shape_xml("window3"),
+        );
+
+        let scene_file = dir.path().join("scene.xml");
+        fs::write(&scene_file, xml).expect("failed to write scene file");
+
+        let material_names: Vec<String> = Python::with_gil(|py| {
+            let scene = Scene::load_xml(&scene_file).expect("scene should load");
+            let py_scene =
+                Bound::new(py, scene).expect("failed to wrap the scene in a Python object");
+            let py_mesh = py_scene
+                .getattr("mesh")
+                .expect("scene should have a `mesh` attribute");
+            py_mesh
+                .getattr("material_names")
+                .expect("mesh should have a `material_names` attribute")
+                .extract()
+                .expect("`material_names` should be extractable as Vec<String>")
+        });
+
+        // 'window1'/'window2' disagree on thickness and are kept
+        // distinguishable under their own ids, but 'window3' has no
+        // 'thickness' override of its own: it must keep the shared generic
+        // name, since 'differt.em._material._populate_materials' never
+        // creates an id-keyed entry for a thickness-less material (it would
+        // otherwise have no matching entry on the Python side at all).
+        assert_eq!(
+            material_names,
+            vec![
+                "window1".to_string(),
+                "window2".to_string(),
+                "itu_glass".to_string(),
+            ]
+        );
+    }
+}