A Guide to Organizing Collections and Rendering with the Blender Python API

What will you learn in this guide?

As Blender scenes grow, it can become harder to keep architectural models, furniture, lighting, and environmental elements organized—and to track which parts are visible or included in the output. The Collection structure in the Blender Python API helps organize objects hierarchically using groups and nested collections. In this guide, we walk through creating a collection and linking it to a scene, adjusting collection visibility, exploring Line Art options, and using render operators.

The examples are based on properties and operations listed in Blender’s current API documentation. Since the documentation does not specify a particular Blender version, test the examples in your current environment before using them. Adapt the collection names and scene structure in the code to suit your project.

Requirements

• Blender and access to the Python API are required. The sources are the current Blender API documentation; they do not specify a particular version number.

• The sources do not mention account or subscription requirements. The documentation also provides no information about hardware requirements for using Blender or render times.

• The examples operate on collections and objects in the scene. Before applying them, it is good practice to keep a copy of important project files and test the code in a small test scene.

Step by step: Organizing a scene with collections

1. Create a new collection and link it to the scene

The code below creates a new collection and links it to the active scene’s master collection. The Blender API documentation lists operations for creating collections and linking child collections. “Furniture” is an example name that could be used to group furniture in an interior project.

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

Creating a collection does not automatically move the scene’s objects into it. You need to manage object membership separately. The objects property of a collection refers to objects directly in that collection, while all_objects includes objects in its nested collections as well. Understanding this distinction helps you accurately assess the total contents of scenes with master collections and nested groups.

2. Build a hierarchy with nested collections

In an architectural visualization file, you can create groups such as furniture and lighting under a parent “Interior” collection. In the Blender API documentation, children is defined as a property for listing direct child collections, while children_recursive lists all nested collections. When exploring the hierarchy, determine which level of content you need.

The all_objects property includes objects in the collection and its nested collections, and is read-only. Therefore, use operations on collection objects and nested collections—not this property—to organize content. The documentation also notes that building the children_recursive list takes time depending on the number of nested collections; keep this in mind when using the property in a deeply nested hierarchy.

3. Manage viewport and render visibility separately

hide_viewport disables a collection in the viewport, while hide_render disables it in renders. The two settings are not interchangeable. For example, you can keep a group hidden in the working viewport but visible in renders by setting separate values as shown below:

collection.hide_viewport = True
collection.hide_render = False

In this example, the collection is hidden in the viewport but not disabled for rendering. Change the values as needed. Checking the result in just one place is not enough: inspect the viewport and the rendered output separately.

4. Set Line Art behavior at the collection level

Blender’s documentation provides options for determining how collections are handled in Line Art calculations. The available modes include INCLUDE, OCCLUSION_ONLY, EXCLUDE, INTERSECTION_ONLY, NO_INTERSECTION, and FORCE_INTERSECTION. These options define different behaviors, such as generating lines from a collection, creating occlusion only, excluding it from calculations, or handling intersection lines.

The example below selects a mode that creates occlusion only for the collection:

collection.lineart_usage = 'OCCLUSION_ONLY'

If you need additional controls for intersections, the documentation also includes the lineart_use_intersection_mask and use_lineart_intersection_priority properties. Intersection priority can be set with lineart_intersection_priority; the API documentation specifies a range of 0 to 255 for this value. Consider these options when your scene uses Line Art and the behavior you need is clear.

Capturing the active view and rendering

The bpy.ops.render.opengl operator is documented for capturing the active viewport. The write_still option saves the image to the output path when animation is disabled:

bpy.ops.render.opengl(write_still=True)

This is not the same as a general scene render. The operator listed in the API as bpy.ops.render.render can be used to start a scene render. The example shows the option for saving a single image:

bpy.ops.render.render(write_still=True)

The documented parameters for the render operator include animation, using the viewport, scene selection, and start and end frames for animation. Frame range options are for animation rendering. Although the API page describes these operations and parameters, it does not specify all the output settings your project may require; check your scene settings before rendering.

Common mistakes

• Treating viewport and render settings as the same: hide_viewport and hide_render are different properties. Verify the desired visibility in both places.

• Overlooking nested collections: objects shows direct members; to include nested collections, take into account the scope of the all_objects property.

• Choosing a Line Art mode at random: The options define different line and intersection behaviors. Choose based on the result you want and check it in a small test scene.

• Mistaking a viewport capture for a scene render: bpy.ops.render.opengl captures the active view; a separate operator is available for a general render.

• Assuming behavior not covered in the API documentation: The sources do not explain specific project settings, render speed, or hardware requirements. Test these details with your own scene and working environment.

Impact on architectural and visualization workflows

Architecture firms and visualization teams can use collections to group models, furniture, lighting, and environmental elements, making scene hierarchies easier to understand. Managing viewport and render visibility separately makes it possible to hide elements that are not needed while working, yet handle the output differently. For drawing-focused presentations that use Line Art, collection-level modes can help determine how groups contribute to line calculations.

This API documentation does not guarantee compatibility with a particular add-on, hardware level, or Blender version. Before setting up automation for shared files in an office, test the code in the Blender environment you use and in a small test file. Also note the source documentation’s CC BY-SA 4.0 license, which applies to use of the documentation content.

Next steps

Start by creating a collection hierarchy in a small test scene, then change viewport and render settings separately and compare the results. If you use Line Art, choose an appropriate mode and check the lines in the output. Verify the scene’s output settings before moving on to the render operators. The API documentation also lists operations for creating and clearing the Cycles texture cache; these are separate operators from collection organization and the basic render workflow.

Source and license

This guide is adapted into Turkish from the Blender Python API documentation for Collection and render operators. Both sources are provided under the CC BY-SA 4.0 license.