Hello and welcome to another episode of scripting for artists.
My name is Evelyn and this episode is about blender collections.
These were introduced in blender 2.80 and
replaced the numbered scene layers and groups.
I'm not recording this as usual at the blender institute
but I'm home right now as so many of you
and as a result the video will be less scripted and I won't have any slides to show.
So we'll just dive into blender and I will show things there.
So in the outlining here,
you can see that we have the same collection with Suzanne in
it like one object and it has that default collection collection one.
So given that this thing here is called the same collection,
let's look at the same object and see if we can find a collection property.
So here we have Suzanne
and as a reminder here we have the convenience variables.
So capital C stands for be point of context and capital D stands for be part of data.
Um You can't use these in your own scripts but you can
use them here in the console while you're figuring things out.
So let's take a look at scene dot
cole then press tab and you can see it already has a collection property. Um
We can get its name,
it's called Master Collection because it's the main scene collection.
Um
and it has a
property called objects.
And if you convert that to a list,
just arrow up and then type list with parenthesis around the line
and there you can see that one object, Suzanne that was here.
Collection objects gives you all the objects
that are directly linked into that collection.
So let's see what happens when you move
Suzanne into collection one it's still indirectly inside
the same collection because it's inside collection one
and collection one is inside the same collection.
But it's no longer in the same collections dot object.
If you want to have really everything then look at all the square objects.
This is like a magical view that will give you everything in the collection itself.
So it contains everything that objects also contains.
But then it also contains everything that is inside collections in the collection.
In the collection in the collection.
And as you can see we have Suzanne.
Yeah.
So as many things in lender collections have to have
a unique name because they are stored in data.
So we have deep fried up data or in the coastal capital D dot collections.
And this gives us the collection one.
It does not contain the scenes master Collection
but it contains all the other collections.
So here we also can get the collections collection one object
and
converted to a list to see what's in there.
And again of course there are Suzanne in there.
So this already gives you a way to given the name
of a collection iterating over all the objects in that collection.
So maybe you want to write an exporter
that exports everything in one particular collection.
Now you know how to access it.
And I'm saying iterate over the objects.
Let's just take a look at how that would happen just to refresh your memory.
So let's say we have a nice little bohemian rhapsody going on here with
For Suzanne's in that one collection.
If we say list the collection dot objects than we get all four of them, of course.
So let's take a little example of how it would
look like in a little bit more complex code.
You would basically say well collection call or call or what you want to call.
It is collections collection one.
And then I can say for ob in
called up objects.
Friend
of name is
pop dot name.
And this is a format string.
It's really useful. You can just type an F before the opening quotes.
And then within curly braces, you can write any expression like ab dot name
and what you can see here.
It lists all the names of all the objects.
So it looks with the for loop,
it looks over all the objects in the collection and then does something with it.
And this could be calling an exporter or this could be
setting a material or it could be changing the
name or whatever you want to do of course.
And in our case it just prints the name.
So let's take a look at creating a collection from python.
This is also done through the data collections collection. So
de dot collections. Let's take a look what do we have?
We have a new function so let's type new tab and you can see that you can type name.
And now we have a new collection called demo.
You want to use this collection as it's given to you because
of course this is now available at the pi data collections. Demo.
Uh huh.
This happens to the best of us. Everybody makes typos, don't worry about it.
Mhm.
We can get given the name Demo we can get the collection again.
This is a big big pitfall that you could fall into because you may think
that that collection that you just created with an M demo will have the name.
Demo. Well let's take a look at what happens when we do it again.
Exactly the same function call just telling blender
to make me a new collection called demo.
But this time we already have a collection that is called Demo.
And as I said collections have to have a unique name.
So what happens is that it calls it demo.0. There are one as your use from lender.
Yeah
but now the name that we ask blender to give the collection
is not the same as the name that the collection was given.
So if you now access.
Okay
beep I. Data collections demo
You will see that you get demo. Of course and not demoted 001.
So what I would say is always when you create a new collection, assign it to a name
like this.
Okay.
And then you're sure that you have the right collection
afterwards. You can change the name.
Mm
Like scripting for artists.
Yeah.
And it will have the new name.
Yeah.
one thing you may notice in the outline er up here
is that the name isn't there? Like the collection is not there yet.
So it exists in the blend file.
It exists in memory but it's not links to the scenes master collection yet.
So how do we do that? Well,
we go to the Master collection.
Yeah.
And then dot and tap to just get a list of everything that's in there.
And
one thing you'll notice is this property called Children.
And that contains all the child collection.
So that's all the collections that are linked into this collection.
So, let's take a look there
and there you find a function called link.
Yeah.
At this collection as a child with this collection. Well, it's a bit cryptic.
Two times this collection referring to different things.
But I think you get the gist. Uh We had our collection in the name collection.
Yeah.
So keep your eyes on the outline. A while. I press enter.
There we go. And now it is part of the same collection.
Linking objects into this new collection is pretty much
the same thing as linking other collections into it.
Instead of using the Children dot link. Your use dot object dot link.
So let's take a look. We have our collection,
it has an empty
empty set of objects. Nothing is in there.
Yeah.
And we can use those objects are linked to Lincoln object to it.
Yeah.
And like that we can add Suzanne 0.3 to it.
Now let's put this into a bit more of a script.
So I'm going to subdivide here and
change the text editor,
creating your script.
Call it uh
move stuff Thought pie.
Yeah.
Always start with improved beep. I
and now let's say we want to move everything that
is inside one collection and move it into another.
Uh So we have to have a collection from
is Bp data collections
Collection one.
And we have something similar collection too.
Yeah.
Is the pi data collection S. F. A. So now we have our two collections.
Let's loop over one and then add all the objects that we find into the other.
So for ob n call from dot objects. Cool too. Dot objects dot link up
and this will already copy. Link all the objects from one collection to the other.
What's left to move is to unlinked from the other collection.
So we need to unlinked from call from.
But that also means removing that object from. Call from dot objects.
So that means that by unblinking we're changing
the thing that we're looping over currently.
And this is not a good idea that you shouldn't do this at best.
It will be unpredictable
and a word stable crash blender and you will lose your data.
The most simple solution for this of course as many of them.
But the simplest is to keep track of the objects that you want to Unlike.
So let's say two unlinked is an empty list
and in this list we will keep track of whatever you want to unlinked later.
So we can say to Owen link dot
append ob
And once this for loop is done, we can loop over this and unlinked everything.
So for up into a link
call from dot objects dot
unlike bob
and this will work. Let's give it a try
and my script failed. Of course.
Let's take a look at the console.
Mm
If we look at the terminal from which has started blender,
you can see that it gives me a runtime error object.
Suzanne 0.3 already in collection S. F A.
And Okay, fair enough. It doesn't like us linking an object that is already in there.
So there's basically two ways in which to
avoid your script breaking because of an error.
Like this.
One is to avoid the error to begin with and
the other is to handle the error when it occurs.
And I think in this case it's easiest to just catch the
error and make sure that our script keeps running when that happens.
So the error says that line number eight is the problem.
So let's take a look at line number eight.
So line eight is this line in the code? It's the linking itself.
Of course that goes wrong.
And you can tell python to just give this line of try and see what happens. So
literally you say try
and then a Colin and like the for loop and the F.
And the other things that we've seen that. And in a column you have to invent the rest.
So that indicates what it needs to try.
And then when we look at the terminal we saw the runtime error,
that is right over here.
That is the type of the exception. And I won't go into detail as to what it all means.
Um Just know that you have to type it here. So that plankton notes that
if an exception occurs in this tribe block of this type.
Uh huh.
Then execute this code over here
and in our case is is fine.
This happens when the object is already in the collection,
which means that we're happy because we wanted to link it there.
It already is there. So it's all fine.
So we can let this pass, which literally means just type past there.
This tells python don't do anything here, ignore the error.
Nothing happened really.
The next line
is of course still important because we still want
to handle this as though the object moved.
So
the linking went bad because it was already there.
It still needs to be unlinked from the original collection so
we can just keep going and this should fix our code.
Let's give it a try
and there we have it.
All the objects have been moved into as if a have been taken away from collection.
And of course we can do the opposite. We can say well
just flip the names around. Run the script again
and there are back again when they started.
So this is how you can move objects between collections.
One final thing we could do which maybe is a little bit useless but just
to give a demo um We can also remove the collection that removed everything from.
So that would be pi data
collections to remove
call from.
So let's flip them around again. We move all the objects from collection one to S. F.
A. And then once that is done we remove the collection
and there we go. Now the collection one is gone.
All the objects have been moved again
and that's how you work with collections from python to end this episode.
Let's take another look at the outline er and there are
a few toggles that you can set like the restriction toggles.
So let's take a look if I want to change the
if you port rendering of this collection you can see in the
point and tool tip which you can enable in the user preferences.
Um you can see that BP data collections S F A dot Hi vieux port is the thing to go to.
So let's take a look there. We take our data
collections S F a dot hide.
Well, there we already have, I render hard select highview board.
Yeah.
And you can just set them to true
back. It falls
and you can play around with this.
Yeah.
And it pretty much does what you would expect from clicking on the icons.
So that's it.
If you have any questions, leave comments and I'll see you in the next episode.