Set Units and Object Position in an Architectural Scene with Blender Python

What will you learn in this guide?

When working on architectural modeling and visualization in Blender, scripting specific tasks with the Python API instead of repeatedly adjusting scene settings by hand can help you apply the same steps consistently across different files. In this guide, you’ll set the scene’s unit system to METRIC, change the position of an object in the scene, create a simple light object, and set the animation frame. The examples are based on the Scene, Object, and UnitSettings descriptions in Blender’s official Python API documentation.

The code here consists of small starter examples to adapt to your own project files. Since they can change the current arrangement of objects in a scene, it’s a good idea to test them on a copy first. The examples don’t assume a specific render engine, add-on, or architectural modeling tool.

Requirements

You’ll need Blender and access to its Python API. The source material refers to current Blender API pages but does not specify a particular Blender version number. Before using the code in a production file, check that the properties are compatible with the API documentation for your installed version. The examples do not specify any account, paid license, or additional add-on requirements.

Run the code snippets in Blender’s Python context; the examples in the documentation use the bpy module and the active view layer. Before running a command, make sure the correct file, scene, and view layer are active. The object-position example targets the first object in the scene, so if the scene is empty, create an object before running this code.

1. Set the scene unit system

Scene data includes time- and render-related settings as well as objects. You can choose a unit system through a scene’s unit_settings property. The API documentation lists NONE, METRIC, and IMPERIAL as options for system. The example below sets the active scene’s system to metric:

import bpy

scene = bpy.context.scene
scene.unit_settings.system = 'METRIC'

This only changes the system setting. The documentation describes the scale_length property as the scale used to convert between Blender units and dimensions. Use this value deliberately and consistently throughout your project, and keep its effect in mind when comparing the dimensions of models from different files. The source shows only the DEFAULT option for the length_unit property, so we don’t assign an undocumented value here.

You can print the current property values to review the unit settings:

import bpy

settings = bpy.context.scene.unit_settings
print(settings.system)
print(settings.scale_length)
print(settings.use_separate)

use_separate is documented as a property that determines whether units are displayed in compound form. This code reads the values; it doesn’t change any settings. Compare the output with your project’s dimensioning requirements before moving on.

2. Change an object’s position in the scene

The location property in an Object data block represents the object’s position in three coordinates. If the scene contains at least one object, the code below assigns a new value to the first object’s position:

import bpy

scene = bpy.context.scene
if len(scene.objects) > 0:
    obj = scene.objects[0]
    obj.location = (5.0, 5.0, 5.0)

The coordinates in this example are the same as the position values in the API documentation’s basic object manipulation example. Replace them with the coordinates you need for your own model. Since the code selects the first object, check the order of objects in the scene and make sure it’s the right target. In projects with multiple objects, assigning a position to the wrong one can disrupt the model layout.

The documentation also describes the object’s location, rotation, and scale, as well as its world-space transformation matrix. This guide focuses on the basic location property; it doesn’t calculate transformations through a matrix or parent relationship. If you need to preserve an existing hierarchy in an architectural model, assess the position change in the context of the relevant parent and constraint setup.

3. Add a light object to the scene

The official API example shows how to create a light data block, attach it to an object, and add the object to the active view layer’s collection. The example below follows the same basic workflow but changes the light’s name and position:

import bpy

view_layer = bpy.context.view_layer
light_data = bpy.data.lights.new(name="Mimari Test Isigi", type='POINT')
light_object = bpy.data.objects.new(
    name="Mimari Test Isigi",
    object_data=light_data
)
view_layer.active_layer_collection.collection.objects.link(light_object)
light_object.location = (5.0, 5.0, 5.0)
light_object.select_set(True)
view_layer.objects.active = light_object

The order of operations matters: first, the light’s data block is created, followed by an object that uses the data; once the object is linked to the active collection, it becomes visible in the scene. The final lines select the object and make it active. The example does not set a value for the light’s render power or other lighting parameters, so it doesn’t promise a particular brightness or render result.

4. Set the animation frame with code

The frame_current property in Scene specifies the current frame. The API documentation recommends using the frame_set() method to immediately update animation data and view layers. For example:

import bpy

scene = bpy.context.scene
scene.frame_set(25)

The frame number here is an example; it does not automatically change the scene’s start and end range. The Scene documentation defines frame_start and frame_end as separate properties. In a scene with animation or camera movement, make sure the target frame falls within the project range and that the desired object state is present at that frame.

What does this offer in architectural and visualization workflows?

For architects, interior designers, and visualization artists, these examples can provide a starting point for scripting tasks such as scene preparation, repeated object placement, and animation frame control. When sharing a scene standard across a team, explicitly showing settings such as the unit system in code makes it easier to track which properties are being changed. However, the examples do not set up automatic dimensioning, coordinate matching between files, or render settings.

The sources provide no information about hardware requirements, license costs, or specific add-ons. Back up your file before applying the code, check that you’re working in the correct scene, and verify compatibility with the API documentation for your Blender installation. In particular, test examples that depend on object order in a small test scene rather than running them directly in a large project file.

Common mistakes

• Running the object-position code in an empty scene: If no first object is found, there’s no target to assign a position to. The condition in the example checks for this.

• Confusing the unit system with the scale value: system and scale_length are separate properties in the documentation. Changing one does not mean the other changes automatically.

• Forgetting to link the object to a collection: In the official light example, linking the new object to the active collection is part of the workflow that places it in the current scene.

• Not checking the frame range: frame_set() sets the current frame; the properties that control the start and end range are separate.

Next steps

Start by trying the code that reads and checks the unit settings, then run the position example on a single test object. Verify the light-creation example in a new scene before adding it to an existing project file. Next, explicitly specify the target object, coordinates, and frame number for your own workflow. Checking the scene and the expected object state after each change helps reduce the risk of applying code to the wrong target.

Sources and license

This guide is adapted into Turkish from the Object, Scene, and UnitSettings pages in the Blender Python API documentation. All three sources are licensed under CC BY-SA 4.0. The basic API usage and property descriptions in the code examples are based on these documents.