blender_csv_import

A simple and fast CSV file importer.

Download here: https://extensions.blender.org/add-ons/csv-importer/

Walkthrough video:

out.mp4

How to Use

Option 1: Drag and drop your CSV file directly into Blender’s viewport.

Option 2: Use the menu: File → Import → CSV

Using the Data

• The imported data will appear in Blender’s Spreadsheet Editor.
• Use the Named Attribute in Geometry Nodes to access the imported data.

And the data will show up in the speadsheet:

you can reproduce the above example with this geometry nodes setup. The corresponding Blender file can be downloaded here

Support this project

Development instructions

1. Install https://github.com/JacquesLucke/blender_vscode
2. Enable the setting "Blender › Addon: Reload On Save"
3. Command+Shift+P -> Blender: Build and Start
4. Start coding with init.py

Build the extension:

For downloading the wheels files, run:

/Applications/Blender.app/Contents/MacOS/Blender -b -P build.py

For building the app for all platforms, run

/Applications/Blender.app/Contents/MacOS/Blender --command extension build --split-platforms

Run tests:

uv sync --all-extras --dev
uv run -m pytest

Changelog

Version 0.1.6

• Add Reload and Hot Reload operators #16 (comment)

• Support for 3D vectors (with potential JSON support in the future: BradyAJohnston/databpy#3 (comment)). Here's a dataframe example

import polars as pl
import numpy as np
from csv_importer.parsers import polars_df_to_bob

df = pl.DataFrame({
    "Star": [
        [58.2, 91.8, 0.0],
        [58.1, 92.2, 0.0]
    ],
    "Is_Visible": [True, False],
    "Intensity": [10, 20],
})

bob = polars_df_to_bob(df, name="Test")

• new functionsupdate_obj_from_csv and update_bob_from_polars_df

from csv_importer.csv import load_csv
from csv_importer.parsers import update_obj_from_csv
from pathlib import Path

csv_path1 = Path("/Users/jan-hendrik/projects/blender_csv_import/docs/sample_datasets/data_california_housing.csv")
csv_path2 = Path("/Users/jan-hendrik/projects/blender_csv_import/docs/sample_datasets/data_gemeran_cities.csv")


bob = load_csv(csv_path1)
print(bob.name)
# out: CSV_data_california_housing

# Make changes to the CSV file using a text editor.
# Important note: The name of the Blender object won't change, only the underlying data.
update_obj_from_csv(bob, csv_path2)

import polars as pl
from csv_importer.parsers import polars_df_to_bob, update_bob_from_polars_df

# Create initial DataFrame with star coordinates
df1 = pl.DataFrame({
    "Star": [
        [58.2, 91.8, 0.0],
        [58.1, 92.2, 0.0]
    ]
})

# Convert DataFrame to 'bob' object
bob = polars_df_to_bob(df1, name="Test")

# Create a second DataFrame with new star coordinates
df2 = pl.DataFrame({
    "Star": [
        [1.2, 1.8, 0.0],
        [1.1, 1.2, 0.0]
    ]
})

# Update 'bob' object with new data from df2
update_bob_from_polars_df(bob, df2)

Version 0.1.5

New Features

• Drag-and-Drop: Added support for drag-and-drop functionality into windows other than the viewport.
• API Import Call: Introduced an API for importing CSV data (note: this feature is not yet stable and may change in the future). Usage examples:

from csv_importer.csv import load_csv
from csv_importer.parsers import polars_df_to_bob

Usage Examples

1. Loading CSV File:

   >>> from csv_importer.csv import load_csv
   >>> bob = load_csv("/Users/jan-hendrik/Desktop/data_california_housing.csv")
   >>> bob
   bpy.data.objects['CSV_data_california_housing']

2. Converting Polars DataFrame:

   from io import StringIO
   import polars as pl
   from csv_importer.parsers import polars_df_to_bob
   
   csv_data = StringIO(
   """FloatVal,IntVal,BoolVal,StringVal
   1.23,10,true,Hello
   4.56,20,false,World"""
   )
   df = pl.read_csv(csv_data)
   bob = polars_df_to_bob(df, name="Test")

---

Blender Version Support

• Supported Versions:
  • Blender 4.3.1 and later.
  • Blender 4.2.5 (requires testing, I did not try this yet).
• Known Issue (Resolved):
  • A bug in earlier Blender versions (issue link) has been fixed.

---

Improvements

• Properly skip string data when processing CSVs.
• Added test coverage for the CSV importer.
• Refactored the project structure for better organization.

---

Additional Updates

• Use a new data wrapper using databpy by @BradyAJohnston.
• Update to latest Polars library version: 1.19.0.

0.1.4

• Rename the imported mesh from "ImportedMesh" to "CSV_filename"