vibephysics 0.2.2__tar.gz → 0.2.3__tar.gz

{vibephysics-0.2.2/src/vibephysics.egg-info → vibephysics-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vibephysics
-Version: 0.2.2
+Version: 0.2.3
 Summary: Physics simulation and annotation tools for Blender
 Author-email: tsunyi <tsunyi@mimiaigen.com>
 Project-URL: Homepage, https://github.com/yourusername/vibephysics
@@ -33,6 +33,47 @@ Requires-Dist: ruff; extra == "dev"
 
 **A lightweight Blender physics simulation framework for creating realistic robot animations, rigid body physics, water dynamics, and comprehensive annotation tools — all running efficiently on CPU.**
 
+## ⚙️ Installation (MacOS)
+
+```bash
+# 1. Create environment
+conda create -n vibephysics python=3.11
+conda activate vibephysics
+
+# 2. Install core package (includes COLMAP mapping & Blender simulation)
+pip install vibephysics
+
+# 3. (Optional) Install GLOMAP backend
+# Linux users: refer to "Linux System Dependencies" below first
+pip install git+https://github.com/shamangary/glomap.git
+```
+
+## 🐧 Linux (Ubuntu) System Dependencies
+If you are on Linux and want to use the **GLOMAP** or **COLMAP** backends, you must install the following C++ development libraries to enable successful compilation:
+
+```bash
+sudo apt-get update
+sudo apt-get install -y \
+    libeigen3-dev \
+    libceres-dev \
+    libgoogle-glog-dev \
+    libboost-all-dev \
+    libsuitesparse-dev \
+    libsqlite3-dev \
+    libgflags-dev \
+    libfreeimage-dev \
+    libmetis-dev
+```
+
+## ⚠️ Troubleshooting (Linker Errors)
+If you are using **Anaconda** on Linux and see an error like `relocation R_X86_64_TPOFF32 ... can not be used when making a shared object`, it is due to a conflict with the Anaconda linker. Fix it by forcing the compiler to use the global-dynamic TLS model:
+
+```bash
+export CXXFLAGS="$CXXFLAGS -fPIC -ftls-model=global-dynamic"
+export CFLAGS="$CFLAGS -fPIC"
+pip install git+https://github.com/shamangary/glomap.git
+```
+
 ## 🎬 Example Results (`sh run_robot.sh`)
 
 ![Result Demo](assets/result_demo.gif)
@@ -93,37 +134,6 @@ Perfect for researchers, animators, and robotics engineers who need physics simu
 - **Open Duck**: We use the [Open Duck blender model](https://github.com/pollen-robotics/Open_Duck_Blender) as demo. We do not own the model. Please refer to the original github repo.
 - **Unitree Go2**: We use the [Unitree Go2 USD model](https://huggingface.co/datasets/unitreerobotics/unitree_model). The model is auto-downloaded when running Go2 examples. We do not own the model.
 
-## ⚙️ Installation
-
-```bash
-# Create and activate environment
-conda create -n vibephysics python=3.11
-conda activate vibephysics
-
-# Install vibephysics
-pip install vibephysics
-
-# Or install from source
-git clone https://github.com/mimiaigen/vibephysics
-cd vibephysics
-pip install -e .
-```
-
-### 🗺️ Mapping & Reconstruction
-The core mapping tools are now built-in!
-
-1. **Incremental COLMAP**: Available immediately after `pip install vibephysics`.
-2. **Global GLOMAP**: Just run your first mapping task! `vibephysics` will automatically prompt and install the optimized GLOMAP backend from GitHub.
-   *(Note: This requires a one-time C++ build which takes a few minutes).*
-
-### Requirements for Simulations
-If you intend to run physics simulations, you also need to install Blender's Python module:
-
-```bash
-# Install Blender module
-pip install bpy
-```
-
 ## Quick Start
 
 ```bash
@@ -310,7 +320,7 @@ VibePhysics integrates high-performance Structure-from-Motion (SfM) engines to c
 from vibephysics import mapping
 
 # 1. Simple Usage (Only image_path is REQUIRED)
-# Defaults: glomap engine, exhaustive matcher, SIMPLE_RADIAL camera
+# Defaults: glomap engine, exhaustive matcher, PINHOLE camera
 mapping.glomap_pipeline(image_path="path/to/images")
 
 # 2. COLMAP Incremental Pipeline
@@ -322,7 +332,7 @@ mapping.glomap_pipeline(
     output_path="output/dir",             # Optional: Defaults to image_path/../mapping_output/
     database_path="path/to/database.db",  # Optional: Defaults to output_path/sparse/database.db
     matcher="exhaustive",                 # Optional: "exhaustive" (default) or "sequential"
-    camera_model="SIMPLE_RADIAL",         # Optional: "PINHOLE", "SIMPLE_RADIAL" (default), "OPENCV", etc.
+    camera_model="PINHOLE",               # Optional: "PINHOLE" (default), "SIMPLE_RADIAL", "OPENCV", etc.
     verbose=True                          # Optional: Set to False to suppress logs
 )
 ```
@@ -333,7 +343,27 @@ mapping.glomap_pipeline(
 | **`output_path`** | No | `mapping_output/` | Directory for results. Creates `sparse/0` and symlinked `images/`. |
 | **`database_path`** | No | `database.db` | Optional path to an existing COLMAP database. |
 | **`matcher`** | No | `exhaustive` | Matching algorithm: `exhaustive` or `sequential`. |
-| **`camera_model`** | No | `SIMPLE_RADIAL` | COLMAP camera model (e.g., `PINHOLE`, `OPENCV`). |
+| **`camera_model`** | No | `PINHOLE` | COLMAP camera model (e.g., `PINHOLE`, `OPENCV`). |
+
+### 🎨 Visualization in Blender
+
+You can load your Colmap/GLOMAP reconstruction directly into Blender for inspection, featuring colored point clouds with high-visibility Geometry Node spheres and correct camera poses.
+
+```python
+from vibephysics import mapping
+
+# Load a sparse model folder (containing cameras.bin, points3D.bin etc.)
+mapping.load_colmap_reconstruction(
+    input_path="output/mapping_output/sparse/0",
+    point_size=0.01  # Adjust point blob size for visibility
+)
+```
+
+**Run the Demo:**
+```bash
+# Visualize an existing reconstruction
+python examples/colmap_format/demo_glomap.py --sparse /path/to/sparse/0 --point-size 0.02
+```
 
 ## Gaussian Splatting (3DGS) (BETA)
 

{vibephysics-0.2.2 → vibephysics-0.2.3}/README.md

@@ -4,6 +4,47 @@
 
 **A lightweight Blender physics simulation framework for creating realistic robot animations, rigid body physics, water dynamics, and comprehensive annotation tools — all running efficiently on CPU.**
 
+## ⚙️ Installation (MacOS)
+
+```bash
+# 1. Create environment
+conda create -n vibephysics python=3.11
+conda activate vibephysics
+
+# 2. Install core package (includes COLMAP mapping & Blender simulation)
+pip install vibephysics
+
+# 3. (Optional) Install GLOMAP backend
+# Linux users: refer to "Linux System Dependencies" below first
+pip install git+https://github.com/shamangary/glomap.git
+```
+
+## 🐧 Linux (Ubuntu) System Dependencies
+If you are on Linux and want to use the **GLOMAP** or **COLMAP** backends, you must install the following C++ development libraries to enable successful compilation:
+
+```bash
+sudo apt-get update
+sudo apt-get install -y \
+    libeigen3-dev \
+    libceres-dev \
+    libgoogle-glog-dev \
+    libboost-all-dev \
+    libsuitesparse-dev \
+    libsqlite3-dev \
+    libgflags-dev \
+    libfreeimage-dev \
+    libmetis-dev
+```
+
+## ⚠️ Troubleshooting (Linker Errors)
+If you are using **Anaconda** on Linux and see an error like `relocation R_X86_64_TPOFF32 ... can not be used when making a shared object`, it is due to a conflict with the Anaconda linker. Fix it by forcing the compiler to use the global-dynamic TLS model:
+
+```bash
+export CXXFLAGS="$CXXFLAGS -fPIC -ftls-model=global-dynamic"
+export CFLAGS="$CFLAGS -fPIC"
+pip install git+https://github.com/shamangary/glomap.git
+```
+
 ## 🎬 Example Results (`sh run_robot.sh`)
 
 ![Result Demo](assets/result_demo.gif)
@@ -64,37 +105,6 @@ Perfect for researchers, animators, and robotics engineers who need physics simu
 - **Open Duck**: We use the [Open Duck blender model](https://github.com/pollen-robotics/Open_Duck_Blender) as demo. We do not own the model. Please refer to the original github repo.
 - **Unitree Go2**: We use the [Unitree Go2 USD model](https://huggingface.co/datasets/unitreerobotics/unitree_model). The model is auto-downloaded when running Go2 examples. We do not own the model.
 
-## ⚙️ Installation
-
-```bash
-# Create and activate environment
-conda create -n vibephysics python=3.11
-conda activate vibephysics
-
-# Install vibephysics
-pip install vibephysics
-
-# Or install from source
-git clone https://github.com/mimiaigen/vibephysics
-cd vibephysics
-pip install -e .
-```
-
-### 🗺️ Mapping & Reconstruction
-The core mapping tools are now built-in!
-
-1. **Incremental COLMAP**: Available immediately after `pip install vibephysics`.
-2. **Global GLOMAP**: Just run your first mapping task! `vibephysics` will automatically prompt and install the optimized GLOMAP backend from GitHub.
-   *(Note: This requires a one-time C++ build which takes a few minutes).*
-
-### Requirements for Simulations
-If you intend to run physics simulations, you also need to install Blender's Python module:
-
-```bash
-# Install Blender module
-pip install bpy
-```
-
 ## Quick Start
 
 ```bash
@@ -281,7 +291,7 @@ VibePhysics integrates high-performance Structure-from-Motion (SfM) engines to c
 from vibephysics import mapping
 
 # 1. Simple Usage (Only image_path is REQUIRED)
-# Defaults: glomap engine, exhaustive matcher, SIMPLE_RADIAL camera
+# Defaults: glomap engine, exhaustive matcher, PINHOLE camera
 mapping.glomap_pipeline(image_path="path/to/images")
 
 # 2. COLMAP Incremental Pipeline
@@ -293,7 +303,7 @@ mapping.glomap_pipeline(
     output_path="output/dir",             # Optional: Defaults to image_path/../mapping_output/
     database_path="path/to/database.db",  # Optional: Defaults to output_path/sparse/database.db
     matcher="exhaustive",                 # Optional: "exhaustive" (default) or "sequential"
-    camera_model="SIMPLE_RADIAL",         # Optional: "PINHOLE", "SIMPLE_RADIAL" (default), "OPENCV", etc.
+    camera_model="PINHOLE",               # Optional: "PINHOLE" (default), "SIMPLE_RADIAL", "OPENCV", etc.
     verbose=True                          # Optional: Set to False to suppress logs
 )
 ```
@@ -304,7 +314,27 @@ mapping.glomap_pipeline(
 | **`output_path`** | No | `mapping_output/` | Directory for results. Creates `sparse/0` and symlinked `images/`. |
 | **`database_path`** | No | `database.db` | Optional path to an existing COLMAP database. |
 | **`matcher`** | No | `exhaustive` | Matching algorithm: `exhaustive` or `sequential`. |
-| **`camera_model`** | No | `SIMPLE_RADIAL` | COLMAP camera model (e.g., `PINHOLE`, `OPENCV`). |
+| **`camera_model`** | No | `PINHOLE` | COLMAP camera model (e.g., `PINHOLE`, `OPENCV`). |
+
+### 🎨 Visualization in Blender
+
+You can load your Colmap/GLOMAP reconstruction directly into Blender for inspection, featuring colored point clouds with high-visibility Geometry Node spheres and correct camera poses.
+
+```python
+from vibephysics import mapping
+
+# Load a sparse model folder (containing cameras.bin, points3D.bin etc.)
+mapping.load_colmap_reconstruction(
+    input_path="output/mapping_output/sparse/0",
+    point_size=0.01  # Adjust point blob size for visibility
+)
+```
+
+**Run the Demo:**
+```bash
+# Visualize an existing reconstruction
+python examples/colmap_format/demo_glomap.py --sparse /path/to/sparse/0 --point-size 0.02
+```
 
 ## Gaussian Splatting (3DGS) (BETA)
 

{vibephysics-0.2.2 → vibephysics-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "vibephysics"
-version = "0.2.2"
+version = "0.2.3"
 description = "Physics simulation and annotation tools for Blender"
 readme = "README.md"
 requires-python = ">=3.11"

{vibephysics-0.2.2 → vibephysics-0.2.3}/src/vibephysics/__init__.py

@@ -16,7 +16,7 @@ Usage:
 Note: This package requires Blender 5.0's Python environment (bpy) for simulation.
 """
 
-__version__ = "0.2.2"
+__version__ = "0.2.3"
 __author__ = "Tsun-Yi Yang"
 
 # Core modules (non-Blender)

{vibephysics-0.2.2 → vibephysics-0.2.3}/src/vibephysics/mapping/__init__.py

@@ -1,5 +1,6 @@
 from .colmap import colmap_pipeline, run_colmap_stage, run_incremental_mapping_stage
 from .glomap import glomap_pipeline, run_glomap_stage
+from .map_visual import load_colmap_reconstruction
 from .utils import prepare_output_directory
 
 __all__ = [
@@ -8,5 +9,6 @@ __all__ = [
     "run_colmap_stage",
     "run_incremental_mapping_stage",
     "run_glomap_stage",
+    "load_colmap_reconstruction",
     "prepare_output_directory"
 ]

{vibephysics-0.2.2 → vibephysics-0.2.3}/src/vibephysics/mapping/colmap.py

@@ -7,7 +7,7 @@ from .utils import prepare_output_directory
 def run_colmap_stage(
     image_path: Path, 
     database_path: Path, 
-    camera_model: str = "SIMPLE_RADIAL", 
+    camera_model: str = "PINHOLE", 
     matcher: str = "exhaustive", 
     verbose: bool = True
 ) -> int:
@@ -86,7 +86,7 @@ def colmap_pipeline(
     output_path: str | Path | None = None,
     database_path: str | Path | None = None,
     matcher: str = "exhaustive",
-    camera_model: str = "SIMPLE_RADIAL",
+    camera_model: str = "PINHOLE",
     verbose: bool = True
 ) -> int:
     """

{vibephysics-0.2.2 → vibephysics-0.2.3}/src/vibephysics/mapping/glomap.py

@@ -41,7 +41,7 @@ def glomap_pipeline(
     output_path: str | Path | None = None,
     database_path: str | Path | None = None,
     matcher: str = "exhaustive",
-    camera_model: str = "SIMPLE_RADIAL",
+    camera_model: str = "PINHOLE",
     verbose: bool = True
 ) -> int:
     """

vibephysics-0.2.3/src/vibephysics/mapping/map_visual.py

@@ -0,0 +1,274 @@
+import bpy
+import pycolmap
+import numpy as np
+from pathlib import Path
+import math
+
+def create_camera_object(image, camera, collection, scale=0.1):
+    """
+    Create a Blender camera object from a Colmap image and camera.
+    """
+    name = image.name
+    
+    # Colmap pose is World-to-Camera (R, t)
+    # pycolmap 3.x uses image.cam_from_world() method
+    if hasattr(image, "cam_from_world") and callable(image.cam_from_world):
+        pose = image.cam_from_world()
+        rot_mat = pose.rotation.matrix()
+        tvec = pose.translation
+    else:
+        # Fallback for older pycolmap
+        qvec = getattr(image, "qvec", np.array([1, 0, 0, 0]))
+        tvec = getattr(image, "tvec", np.zeros(3))
+        # Manual qvec to rotmat if function is missing
+        if hasattr(pycolmap, "qvec_to_rotmat"):
+            rot_mat = pycolmap.qvec_to_rotmat(qvec)
+        else:
+            # Standard Hamilton quaternion to rotation matrix
+            w, x, y, z = qvec
+            rot_mat = np.array([
+                [1 - 2*y**2 - 2*z**2, 2*x*y - 2*z*w, 2*x*z + 2*y*w],
+                [2*x*y + 2*z*w, 1 - 2*x**2 - 2*z**2, 2*y*z - 2*x*w],
+                [2*x*z - 2*y*w, 2*y*z + 2*x*w, 1 - 2*x**2 - 2*y**2]
+            ])
+    
+    # Inverse rotation and translation to get Camera-to-World
+    rot_mat_inv = rot_mat.T
+    tvec_inv = -rot_mat_inv @ tvec
+    
+    # Create Camera Data
+    cam_data = bpy.data.cameras.new(name=f"CamData_{name}")
+    cam_obj = bpy.data.objects.new(name=name, object_data=cam_data)
+    collection.objects.link(cam_obj)
+    
+    # Construct 4x4 matrix in OpenCV frame (X-right, Y-down, Z-forward)
+    mat_world_cv = np.eye(4)
+    mat_world_cv[:3, :3] = rot_mat_inv
+    mat_world_cv[:3, 3] = tvec_inv
+    
+    # Convert from OpenCV to Blender coordinate system
+    # Blender camera looks down -Z, Y is up.
+    # We rotate 180 degrees around X to flip Y and Z.
+    transform_matrix = np.array([
+        [1, 0, 0, 0],
+        [0, -1, 0, 0],
+        [0, 0, -1, 0],
+        [0, 0, 0, 1]
+    ])
+    
+    final_matrix = mat_world_cv @ transform_matrix
+    
+    # Assign to object
+    import mathutils
+    m = mathutils.Matrix(final_matrix.tolist())
+    cam_obj.matrix_world = m
+    
+    # Set camera intrinsics
+    # Params mapping depends on camera model
+    width = camera.width
+    height = camera.height
+    cam_data.sensor_width = 36.0 # standard 36mm sensor
+    
+    # f_mm = f_px * sensor_width / width_px
+    f_px = 1000.0 # fallback
+    
+    # Get camera model name
+    if hasattr(camera, "model") and hasattr(camera.model, "name"):
+        model = camera.model.name
+    else:
+        model = getattr(camera, "model_name", "UNKNOWN")
+    
+    params = camera.params
+    
+    if model in ["SIMPLE_PINHOLE", "SIMPLE_RADIAL"]:
+        # f, cx, cy
+        f_px = params[0]
+    elif model in ["PINHOLE", "OPENCV", "FULL_OPENCV"]:
+        # fx, fy, cx, cy
+        f_px = (params[0] + params[1]) / 2.0
+    
+    cam_data.lens = f_px * cam_data.sensor_width / width
+    
+    return cam_obj
+
+def create_point_cloud(points3D, collection, name="PointCloud", point_size=0.03):
+    """
+    Create a point cloud visualization using a mesh with vertices and colors.
+    Uses Geometry Nodes to make points visible as spheres.
+    """
+    mesh = bpy.data.meshes.new(name=name)
+    obj = bpy.data.objects.new(name=name, object_data=mesh)
+    collection.objects.link(obj)
+    
+    # Extract points and colors
+    xyz = []
+    rgb = []
+    
+    for p_id, p in points3D.items():
+        xyz.append(p.xyz)
+        rgb.append(p.color / 255.0) # Normalize to 0-1
+        
+    if not xyz:
+        print("No points found in reconstruction.")
+        return obj
+        
+    # Create mesh
+    mesh.from_pydata(xyz, [], [])
+    mesh.update()
+    
+    # Add colors as a generic attribute
+    if rgb:
+        # Check Blender version for attribute creation
+        if hasattr(mesh.attributes, "new"):
+            color_attr = mesh.attributes.new(name="Color", type='FLOAT_COLOR', domain='POINT')
+            color_attr.data.foreach_set("color", [c for color in rgb for c in (*color, 1.0)]) # RGBA
+    
+    # Simple Geometry Nodes setup to render points as spheres
+    modifier = obj.modifiers.new(name="PointVisualizer", type='NODES')
+    
+    # Setup node tree
+    node_tree = bpy.data.node_groups.new(name="PointVisualizerTree", type='GeometryNodeTree')
+    
+    # In Blender 4.0+, we use interface to add sockets
+    if hasattr(node_tree, "interface"):
+        if not any(item.name == "Geometry" for item in node_tree.interface.items_tree if item.item_type == 'SOCKET'):
+             node_tree.interface.new_socket(name="Geometry", in_out='INPUT', socket_type='NodeSocketGeometry')
+             node_tree.interface.new_socket(name="Geometry", in_out='OUTPUT', socket_type='NodeSocketGeometry')
+    else:
+        # Older Blender fallback
+        if "Geometry" not in node_tree.inputs:
+            node_tree.inputs.new('NodeSocketGeometry', "Geometry")
+        if "Geometry" not in node_tree.outputs:
+            node_tree.outputs.new('NodeSocketGeometry', "Geometry")
+    
+    links = node_tree.links
+    nodes = node_tree.nodes
+    
+    # Clear default nodes
+    nodes.clear()
+    
+    # Input/Output
+    node_in = nodes.new('NodeGroupInput')
+    node_out = nodes.new('NodeGroupOutput')
+    
+    # Point to Volume / Instances
+    node_m2p = nodes.new('GeometryNodeMeshToPoints')
+    node_inst = nodes.new('GeometryNodeInstanceOnPoints')
+    node_sph = nodes.new('GeometryNodeMeshIcoSphere')
+    node_sph.inputs['Radius'].default_value = point_size
+    node_sph.inputs['Subdivisions'].default_value = 1
+    
+    # Realize Instances to propagate attributes (like Color)
+    node_realize = nodes.new('GeometryNodeRealizeInstances')
+    
+    # Material
+    node_mat = nodes.new('GeometryNodeSetMaterial')
+    
+    # Material setup
+    mat_name = "PointCloudMaterial"
+    if mat_name not in bpy.data.materials:
+        mat = bpy.data.materials.new(name=mat_name)
+        mat.use_nodes = True
+        nodes_mat = mat.node_tree.nodes
+        links_mat = mat.node_tree.links
+        nodes_mat.clear()
+        
+        node_out_mat = nodes_mat.new('ShaderNodeOutputMaterial')
+        node_principled = nodes_mat.new('ShaderNodeBsdfPrincipled')
+        # Use Attribute node to get the vertex color
+        node_attr = nodes_mat.new('ShaderNodeAttribute')
+        node_attr.attribute_name = "Color"
+        node_attr.attribute_type = 'GEOMETRY'
+        
+        links_mat.new(node_attr.outputs['Color'], node_principled.inputs['Base Color'])
+        links_mat.new(node_principled.outputs['BSDF'], node_out_mat.inputs['Surface'])
+    else:
+        mat = bpy.data.materials[mat_name]
+        
+    # Assign material to object slots (important for some Blender versions to see attributes)
+    if mat.name not in obj.data.materials:
+        obj.data.materials.append(mat)
+        
+    node_mat.inputs['Material'].default_value = mat
+    
+    # Link nodes
+    links.new(node_in.outputs[0], node_m2p.inputs['Mesh'])
+    links.new(node_m2p.outputs['Points'], node_inst.inputs['Points'])
+    links.new(node_sph.outputs['Mesh'], node_inst.inputs['Instance'])
+    links.new(node_inst.outputs['Instances'], node_realize.inputs['Geometry'])
+    links.new(node_realize.outputs['Geometry'], node_mat.inputs['Geometry'])
+    links.new(node_mat.outputs['Geometry'], node_out.inputs[0])
+    
+    modifier.node_group = node_tree
+    
+    # Attempt to set viewport shading to MATERIAL for better UX
+    if bpy.context.screen:
+        for area in bpy.context.screen.areas:
+            if area.type == 'VIEW_3D':
+                for space in area.spaces:
+                    if space.type == 'VIEW_3D':
+                        space.shading.type = 'MATERIAL'
+    
+    return obj
+
+def load_colmap_reconstruction(
+    input_path: str, # Path to sparse/0 folder
+    collection_name: str = "Reconstruction",
+    import_cameras: bool = True,
+    import_points: bool = True,
+    camera_scale: float = 0.1,
+    point_size: float = 0.03,
+    rotation: tuple = (-90, 0, 0) # Global rotation in degrees (Euler XYZ)
+):
+    """
+    Load Colmap reconstruction output (sparse folder) into Blender.
+    """
+    input_dir = Path(input_path)
+    if not input_dir.exists():
+        print(f"Error: Path {input_dir} does not exist.")
+        return
+
+    print(f"Loading Colmap reconstruction from {input_dir}...")
+    recon = pycolmap.Reconstruction(input_dir)
+    
+    # Create collection
+    if collection_name in bpy.data.collections:
+        col = bpy.data.collections[collection_name]
+    else:
+        col = bpy.data.collections.new(collection_name)
+        bpy.context.scene.collection.children.link(col)
+        
+    # Create a root object for the whole reconstruction to allow global manipulation
+    root_name = f"{collection_name}_Root"
+    if root_name in bpy.data.objects:
+        root_obj = bpy.data.objects[root_name]
+    else:
+        root_obj = bpy.data.objects.new(root_name, None)
+        col.objects.link(root_obj)
+    
+    # Apply global rotation to the root
+    root_obj.rotation_mode = 'XYZ'
+    root_obj.rotation_euler = [math.radians(a) for a in rotation]
+        
+    if import_points:
+        print(f"Importing {len(recon.points3D)} points...")
+        pc_obj = create_point_cloud(recon.points3D, col, point_size=point_size)
+        pc_obj.parent = root_obj
+        
+    if import_cameras:
+        print(f"Importing {len(recon.images)} cameras...")
+        for img_id, image in recon.images.items():
+            if image.camera_id in recon.cameras:
+                cam = recon.cameras[image.camera_id]
+                cam_obj = create_camera_object(image, cam, col, scale=camera_scale)
+                cam_obj.parent = root_obj
+                # Keep the same world matrix when parenting if the root has no rotation yet
+                # or just set it relative to parent. 
+                # Since we set root rotation ABOVE, we should set matrix_world AFTER parenting 
+                # or use matrix_local if we want it to be relative.
+                # The create_camera_object returns an object with matrix_world set for the SfM space.
+                # If we parent it to root_obj, and then set matrix_world again, 
+                # it will stay in the correct spot while being a child.
+                
+    print("Done.")
+

{vibephysics-0.2.2 → vibephysics-0.2.3/src/vibephysics.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vibephysics
-Version: 0.2.2
+Version: 0.2.3
 Summary: Physics simulation and annotation tools for Blender
 Author-email: tsunyi <tsunyi@mimiaigen.com>
 Project-URL: Homepage, https://github.com/yourusername/vibephysics
@@ -33,6 +33,47 @@ Requires-Dist: ruff; extra == "dev"
 
 **A lightweight Blender physics simulation framework for creating realistic robot animations, rigid body physics, water dynamics, and comprehensive annotation tools — all running efficiently on CPU.**
 
+## ⚙️ Installation (MacOS)
+
+```bash
+# 1. Create environment
+conda create -n vibephysics python=3.11
+conda activate vibephysics
+
+# 2. Install core package (includes COLMAP mapping & Blender simulation)
+pip install vibephysics
+
+# 3. (Optional) Install GLOMAP backend
+# Linux users: refer to "Linux System Dependencies" below first
+pip install git+https://github.com/shamangary/glomap.git
+```
+
+## 🐧 Linux (Ubuntu) System Dependencies
+If you are on Linux and want to use the **GLOMAP** or **COLMAP** backends, you must install the following C++ development libraries to enable successful compilation:
+
+```bash
+sudo apt-get update
+sudo apt-get install -y \
+    libeigen3-dev \
+    libceres-dev \
+    libgoogle-glog-dev \
+    libboost-all-dev \
+    libsuitesparse-dev \
+    libsqlite3-dev \
+    libgflags-dev \
+    libfreeimage-dev \
+    libmetis-dev
+```
+
+## ⚠️ Troubleshooting (Linker Errors)
+If you are using **Anaconda** on Linux and see an error like `relocation R_X86_64_TPOFF32 ... can not be used when making a shared object`, it is due to a conflict with the Anaconda linker. Fix it by forcing the compiler to use the global-dynamic TLS model:
+
+```bash
+export CXXFLAGS="$CXXFLAGS -fPIC -ftls-model=global-dynamic"
+export CFLAGS="$CFLAGS -fPIC"
+pip install git+https://github.com/shamangary/glomap.git
+```
+
 ## 🎬 Example Results (`sh run_robot.sh`)
 
 ![Result Demo](assets/result_demo.gif)
@@ -93,37 +134,6 @@ Perfect for researchers, animators, and robotics engineers who need physics simu
 - **Open Duck**: We use the [Open Duck blender model](https://github.com/pollen-robotics/Open_Duck_Blender) as demo. We do not own the model. Please refer to the original github repo.
 - **Unitree Go2**: We use the [Unitree Go2 USD model](https://huggingface.co/datasets/unitreerobotics/unitree_model). The model is auto-downloaded when running Go2 examples. We do not own the model.
 
-## ⚙️ Installation
-
-```bash
-# Create and activate environment
-conda create -n vibephysics python=3.11
-conda activate vibephysics
-
-# Install vibephysics
-pip install vibephysics
-
-# Or install from source
-git clone https://github.com/mimiaigen/vibephysics
-cd vibephysics
-pip install -e .
-```
-
-### 🗺️ Mapping & Reconstruction
-The core mapping tools are now built-in!
-
-1. **Incremental COLMAP**: Available immediately after `pip install vibephysics`.
-2. **Global GLOMAP**: Just run your first mapping task! `vibephysics` will automatically prompt and install the optimized GLOMAP backend from GitHub.
-   *(Note: This requires a one-time C++ build which takes a few minutes).*
-
-### Requirements for Simulations
-If you intend to run physics simulations, you also need to install Blender's Python module:
-
-```bash
-# Install Blender module
-pip install bpy
-```
-
 ## Quick Start
 
 ```bash
@@ -310,7 +320,7 @@ VibePhysics integrates high-performance Structure-from-Motion (SfM) engines to c
 from vibephysics import mapping
 
 # 1. Simple Usage (Only image_path is REQUIRED)
-# Defaults: glomap engine, exhaustive matcher, SIMPLE_RADIAL camera
+# Defaults: glomap engine, exhaustive matcher, PINHOLE camera
 mapping.glomap_pipeline(image_path="path/to/images")
 
 # 2. COLMAP Incremental Pipeline
@@ -322,7 +332,7 @@ mapping.glomap_pipeline(
     output_path="output/dir",             # Optional: Defaults to image_path/../mapping_output/
     database_path="path/to/database.db",  # Optional: Defaults to output_path/sparse/database.db
     matcher="exhaustive",                 # Optional: "exhaustive" (default) or "sequential"
-    camera_model="SIMPLE_RADIAL",         # Optional: "PINHOLE", "SIMPLE_RADIAL" (default), "OPENCV", etc.
+    camera_model="PINHOLE",               # Optional: "PINHOLE" (default), "SIMPLE_RADIAL", "OPENCV", etc.
     verbose=True                          # Optional: Set to False to suppress logs
 )
 ```
@@ -333,7 +343,27 @@ mapping.glomap_pipeline(
 | **`output_path`** | No | `mapping_output/` | Directory for results. Creates `sparse/0` and symlinked `images/`. |
 | **`database_path`** | No | `database.db` | Optional path to an existing COLMAP database. |
 | **`matcher`** | No | `exhaustive` | Matching algorithm: `exhaustive` or `sequential`. |
-| **`camera_model`** | No | `SIMPLE_RADIAL` | COLMAP camera model (e.g., `PINHOLE`, `OPENCV`). |
+| **`camera_model`** | No | `PINHOLE` | COLMAP camera model (e.g., `PINHOLE`, `OPENCV`). |
+
+### 🎨 Visualization in Blender
+
+You can load your Colmap/GLOMAP reconstruction directly into Blender for inspection, featuring colored point clouds with high-visibility Geometry Node spheres and correct camera poses.
+
+```python
+from vibephysics import mapping
+
+# Load a sparse model folder (containing cameras.bin, points3D.bin etc.)
+mapping.load_colmap_reconstruction(
+    input_path="output/mapping_output/sparse/0",
+    point_size=0.01  # Adjust point blob size for visibility
+)
+```
+
+**Run the Demo:**
+```bash
+# Visualize an existing reconstruction
+python examples/colmap_format/demo_glomap.py --sparse /path/to/sparse/0 --point-size 0.02
+```
 
 ## Gaussian Splatting (3DGS) (BETA)
 

{vibephysics-0.2.2 → vibephysics-0.2.3}/src/vibephysics.egg-info/SOURCES.txt

@@ -36,6 +36,7 @@ src/vibephysics/foundation/water.py
 src/vibephysics/mapping/__init__.py
 src/vibephysics/mapping/colmap.py
 src/vibephysics/mapping/glomap.py
+src/vibephysics/mapping/map_visual.py
 src/vibephysics/mapping/pipeline.py
 src/vibephysics/mapping/utils.py
 src/vibephysics/setup/__init__.py