A Guide to Organizing Collections and View Layers with Blender Python

What will you learn in this guide?

Architectural visualization scenes can bring together building shells, interior elements, furniture, and many other objects. As a scene grows, it becomes increasingly important to group its contents and manage different working views. Blender’s Python API lets you link objects to collections and use View Layers to control which parts of the collection hierarchy are active.

In this guide, you’ll learn how to create a collection with Python, link it to the scene, add the active object to it, and exclude the collection from the active View Layer. We’ll also look at the differences between object visibility settings and collection and View Layer organization. The examples are based on Blender’s official Python API documentation and the scene and object API notes published for Blender 2.80.

Requirements

Run the examples in a Blender environment that supports the Blender Python API. The code accesses the active scene through bpy and, where needed, the active object. The first example creates a collection directly with bpy.data.collections.new and links it to the scene’s root collection; it does not require an active collection beforehand. The separate example that links the active object to the new collection skips that linking step if there is no active object.

The documentation does not specify a particular Blender version, user account, or additional software requirements. Check the API behavior in your installed Blender version before using the code. The Blender 2.80 developer documentation describes API changes from the 2.8x era, while the current API pages document Scene and Object properties. Keep these differences in mind when working with scripts written for older versions.

Set up a collection structure step by step

1. Distinguish the roles of collections and View Layers

During the Blender 2.7x era, scenes could be organized using 20 fixed layers. With the API changes in 2.8x, object organization moved to collections, while View Layers took over control of which parts of the collection hierarchy are visible and available for rendering. For this reason, don’t confuse scene-layer properties found in older scripts with the newer collection system.

Collections group objects and other collections hierarchically. View Layers determine which parts of that structure are active. Creating a collection does not automatically move objects into it; you must link them separately.

2. Add a new collection to the scene

The following example links a new collection named Mimari_Govde beneath the active scene’s root collection. The code creates the collection and then adds it to the scene hierarchy:

import bpy

scene = bpy.context.scene
collection = bpy.data.collections.new("Mimari_Govde")
scene.collection.children.link(collection)

bpy.data.collections.new creates the collection. scene.collection.children.link links it to the scene’s root collection. This example doesn’t use an active object or require an active collection beforehand. If a collection with the same name already exists in the file, check the existing scene structure before running the script again.

3. Link the active object to the new collection

Once the collection has been created, you can use the following example to link the active object to it:

obj = bpy.context.object

if obj is not None:
    collection.objects.link(obj)

If there’s an active object, the collection link is added; if there isn’t, the code inside the condition doesn’t run. This link does not duplicate the object. According to Blender’s developer documentation, the same object can belong to multiple collections and still remain a single object.

In architectural scenes, this distinction helps you organize objects without duplicating their data. However, the example code doesn’t remove the object from its existing collections; it only links it to the new collection as well. Check the object’s other collection links separately.

4. Exclude the collection from the active View Layer

If the collection is directly beneath the scene’s root collection, you can exclude it using the relevant LayerCollection in the active View Layer:

bpy.context.view_layer.layer_collection.children["Mimari_Govde"].exclude = True

This line excludes the Mimari_Govde collection from the active View Layer. To include it again, set exclude to False. The code assumes that the collection is a direct child in the View Layer hierarchy. If it’s nested inside another collection, access it at the correct level of the hierarchy.

View Layers control which parts of the collection structure are active. This isn’t the same as changing visibility properties on individual objects. When assessing the result, consider whether the objects are also linked to other collections and how your View Layer is structured.

5. Manage object visibility separately

If you need to control a specific object rather than collection visibility, you can use object properties. hide_viewport affects object visibility in the viewport, while hide_render affects visibility in renders. For example, to hide the active object from rendering:

obj = bpy.context.object

if obj is not None:
    obj.hide_render = True

This changes render visibility only. The separate documented property for hiding an object in the viewport is hide_viewport. Choose the property that matches the desired result; don’t use the two interchangeably.

Common mistakes

Assuming objects are added automatically when you create a collection: Creating a collection and linking an object to it are separate operations. Link the relevant object to the collection separately.

Using old scene-layer methods with the new API: Collection and View Layer organization changed with 2.8x. Don’t use code such as object.layers from older scripts without checking how it compares with the current collection structure.

Confusing a collection link with copying an object: The same object can belong to multiple collections. Linking it to a collection doesn’t create a new object or a copy of its geometry.

Looking at the wrong level of the View Layer hierarchy: The example exclusion line assumes the collection is a direct child of the active layer. For nested collections, adjust the access path to match the actual scene hierarchy.

Treating viewport and render visibility as the same setting: hide_viewport and hide_render are separate properties. Identify whether the issue is in the viewport or the rendered output, then change the relevant property.

Impact on architectural and visualization workflows

Collections can be used to group the building shell, furniture, or other scene elements that need to be controlled together. View Layer organization manages which parts of this collection hierarchy are active. This structure can help keep complex scenes organized and make it easier to manage visibility by group.

This approach may be useful for architecture firms, interior designers, and archviz artists who want to build a repeatable organization system for Blender scenes with Python. However, the sources don’t promise compatibility with a particular render engine, performance gains, or hardware benefits. For project work, check the Blender version, the actual collection hierarchy, and the workflow for sharing the file with others.

Next steps

Start by running the collection-creation example on a copy of your file. Then try the linking step with an active object and confirm that the object can belong to multiple collections. Before running the View Layer exclusion code, verify where the collection sits within the active layer.

Next, test hide_viewport and hide_render separately to determine which visibility setting meets your needs. If you plan to use the scripts with different Blender versions, consult the API documentation for the version you’ll run the code in, and test changes before applying them to your project file.

Sources and license

“Blender 2.80: Scene and Object API” (K2) in the Blender Developer documentation describes changes to collections and the View Layer structure. The Blender Python API documentation for Scene (K1) and Object (K4) is licensed under CC BY-SA 4.0. This guide adapts the technical information in those sources into Turkish and explains it with original examples.