4

Given a QgsVectorLayer type variable layer, I have seen both the .addMapLayer() and .layerTreeRoot().insertChildNode() methods of QgsProject.instance() being used to add a layer to QGIS, e.g. in this answer, extracted below:

QgsProject.instance().addMapLayer(layer)

QgsProject.instance().layerTreeRoot().insertChildNode(-1, QgsLayerTreeLayer(layer))

I am a bit confused about the difference between the two methods in terms of their functions and why two storage systems are needed for the list of all layers in QGIS. My questions are:

What's the difference between the two, and when should one use one vs the other? (and more generally .mapLayers vs layerTreeRoot's children)

Can one be used without the other, or are they always required to be used together?

(This is with QGIS 3.22 LTR)

tinlyx
  • 11,057
  • 18
  • 71
  • 119

1 Answers1

4

The layerTree is simply a visual display based on a QTreeView. Adding a layer to the layerTree (e.g. using .layerTreeRoot().insertChildNode()) does not really add the layer to the current project, it only inserts a node (a row) in the layer tree panel. Thats purely visual action, QGIS is not aware of the layer you have added. The layer is not saved anywhere in QGIS internal map layer storage.

Consider this small example:

layer1 = QgsVectorLayer("Point", "Layer 1", "memory")
QgsProject.instance().layerTreeRoot().insertChildNode(-1, QgsLayerTreeLayer(layer1))

If you simply execute the above in a new project it will add a node to the layer tree panel. If you then save the project and reload it, the layer will be gone. Only the named node in the layer tree will persist.

On the other hand, by using addMapLayer the given layer is added to the layer storage of the current project. At the same time the layer storage is connected to the layer tree, so that each added layer will be automatically inserted into the layer tree (see QgsLayerTreeRegistryBridge class).

Consider this next example:

layer2 = QgsVectorLayer("Point", "Layer 2", "memory")
QgsProject.instance().addMapLayer(layer2)

This still inserts a new node in the layer tree panel. But if you now save and reload the project, the layer will persist. That's because it was added to the layer store and not only visually to the layer tree.

So in general, .layerTreeRoot().insertChildNode() can hardly be used meaningfully on its own, whereas addMapLayer can be used on its own (because it implicitly also does the insertion into the layer tree). They are not always required to be used together, but can be used together if you want to insert the layer at a specified position in the layer tree, e.g. for inserting the layer into a group.

By default addMapLayer inserts layers at the first position of the root node. If you want to change that behaviour you need to use both together as such:

layer3 = QgsVectorLayer("Point", "Layer 3", "memory")
QgsProject.instance().addMapLayer(layer3, False) # False so that it doesn't get inserted at default position
QgsProject.instance().layerTreeRoot().insertChildNode(2, QgsLayerTreeLayer(layer3)) # instead insert it on our own (at index/row 2)
CodeBard
  • 3,511
  • 1
  • 7
  • 20