Your Own Operator | Scripting for Artists [8]

hello and welcome to scripting for artists my name is Simeon and in this episode I will show you how to create your own operator so far we only created snippets of code you can use them but they're not the most user-friendly many people have asked for ways to create menus and buttons and custom panels and stuff in this episode we will not look at that yet but we will look at a necessary first step which is creating your first operator first we will look at what an operator is exactly then we will see how to create your own operator and how to make it more flexible by passing parameters to it and then we conclude by limiting the operator to specific context an operator is the glue between menus buttons and hotkeys and the code that should be executed by them in the first episode we already worked with operators by copy pasting them from menus and buttons into our own script operators can be implemented in blender itself in the C programming language or they can of course be written in Python and no matter how they're made they all have the same ingredients first is an identifier so this is what you would put after that be Python ops so in this operator example it's far from complete but we're building it up so in this example it would be B Python op start as if a dot example these are always in the form some category dot a name I usually is best to pick a category that already exists like object or mesh or sculpt or whatever is suitable for your your operator but as you can see you can also create your own then we have a label this is what appears on the menu items and buttons and a description that is shown as a tooltip then everything is combined into a class and this is something that will we'll look at in a minute for now just think of it as some pot in which we ain't got all the ingredients of our operator you can see that the class is named after the operator so we have the category in capitals then ot for the operator type and then the rest of the identifiers so far we've seen description but not actual code yet and this can be added in in different ways for different purposes so here are the possibilities from simple to complex you have execute this is where you put the main functionality of the code if you want to create 600 then this is placed it do it the execute function is also what gets called from Python directly so if you call an operator like be part of opposite something that's something this is the function that gets called then we have invoked this function is called when the operator is called for a menu or a button if you want to do something extra in that case you won't have slightly different behavior then you can do that in invoke and you can then call your execute function from there and now we get to the most complex that modal one the modal function is for special operators that need to run for a longer period of time this receives all kinds of events from blender from when you move your mouse you click on buttons you use the keyword that kind of cell things like the blender cloud texture browser or LCD cuckoos retopo flower implemented like this if after all of this you're in doubt about which function to use keep it simple just use the execute function if that turns out not to be able to do what you want to do then have a concrete reason to look at something more complex but before that just keep things simple now let's turn this into an actual operator that we can use let's create some more monkeys let's start by removing what we don't need let's keep it simple just an execute function if you look at the mesh operators you can see that they start with B PI ops mesh primitive monkey add for example or error V PI of smash primitive ecosphere add so all the operators that create in your mesh object they start with mesh so let's keep doing that so the ID name becomes mesh and if we're going to create a monkey grid so monkey grid label monkey grid the tooltip will be let's spread some joy and then the class name we have to change that becomes the category and score ot underscore monkey grid the execute function has to do something but it also has to tell blender whether everything succeeded or not so everything was alright you returned finished and that tells blender that the code actually performed well but maybe your operator work maybe it is for extruding a mesh and the mesh doesn't have any vertices so in that case you return counselled there are a few other options and they are all described in the manual to go there you go to help and then python api reference and then to the section about be part of ops so let's assume that everything will work correctly we will return finished and now all we have to do is put the code here that creates our monkey grid so let's copy the code from chapter 3 of scripting for artists and put it here so this creates our 600 monkeys in rows of 25 having one unit like been a unit between them the operators almost done already so we have all the ingredients here the only thing that we need to do now is to tell blender that this operator exists and this is called registration fortunately this is rather simple we just call be peyote or register class and then the name of the class in our case mesh ot monkey grid for symmetry there should also be a unregister function so that looks like this instead of calling register closet calls unregistered class so basically and does what the register function was doing and then we're almost there it's just that as you know when you have a function like this it's not automatically called when you run the script and there's a little trick for this if you add some magic like this in here and it looks a bit weird but basically what this means is that if this script is run then it should call the register function there's multiple ways in which blender can access your script it can execute it but it can also be imported from something else just like we import be PI other code can import this file as well so there's a distinction between being imported from somewhere else and being run and only when it's being run intruded called the register function and that is what this code does so now what we can do let's just name this monkey grip PI for good measure and then let's click Play and nothing happens which is kind of a good thing we didn't see any error message our code doesn't show any message so the silence is kind of good here so let's see what happens now leave hi pops - there we go we can create a monkey grid the operator is there let's spread some joy let's not call it here let's see if we can find our new operator here in the f3 menu with a monkey and there's your monkey grid so that's really cool press ENTER to execute it and as you can see blendin uh freezes one is creating the 600 monkeys and this is what happens when you do something that takes time in the execute function and that is okay the code is part of this blend file so let's see what happens when we create a new blend file and as you can see the operator is still there it's been loaded into memory blender it's been registered and it just keeps ticking around now let's see what happens if we restart blender and now the monkey grid operator is no longer there and this is because blender doesn't just execute all the scripts that it can find in a blend file you have to tell it to do that first you have to make sure that the name of the text file ends in dot py and then here in the text menu you can check the register check box now let's save restart blender and now it's there so let's have some fun and add some parameters when you add a cube what you see here on the left is called the redo panel when you open it you see different parameters that you can set so what happens is that when you change your parameters value blender pushes the undo button automatically and then re execute the operator and that is why it's called the redo panel because it's redoing things all the time so let's add support for the redo panel to our operator we start by declaring the properties that we want to add and this will be the number of monkeys in the x-direction number of monkeys in the y-direction and sighs just like operators Levin be pointed ops the properties live in be part of props so again if you want to have more information just go to help Python API reference and then click on the beep idle props section I will show you what it looks like let's call it count X V PI props in property instance for integer which means the whole number because we cannot have off monkeys so count X has to be either one or two or three but can ever be like two point five or something so it's whole numbers only and this declares that we want to have that property there was a big difference between the Colin that we have here and the equal sign that we have there this sets a name to a value and this is for things that just have to be set we have to set bail ID name to mesh monkey grid to make it work but here we don't really set anything we just declared to blender this is an in property please act accordingly you can add some parameters here to change behavior first of all we should set a name we can call it X it may be a bit cryptic but for now it will do and we can add a description number of monkeys in the x-direction so let's copy this to that y name is y and number of monkeys in the y-direction and we have a size which is another be part corrupt slot float property float stands for floating point it's a technical term for just decimal numbers maybe the size description is size of age monkey so this gives us our properties but they're not used yet so let's take a look at the execute function where we're supposed to use them this comment it has to go because we no longer creating 600 monkeys in rows of 25 but it's all flexible so let's remove that for now now we have to access the properties so we've declared them and this self gives us access to the actual value self is a pointing thing and I won't go into detail here about what it represents just know that if you declare a property here as count X then you can access it here as self count X so the total number of monkeys it's the number of monkeys in the X and in the Y direction and this 25 here was the number of monkeys in the X direction and then all that this left is to set a size and that's it let's give it a try let's see what happens in the console first and there you can see our properties count X count Y size and they're all equal to zero because we haven't set any default yet and there we have our three monkeys before we go to actually call it from the viewport let's set some sensible defaults default is three for the Y default is two I choose different values there on purpose this is a default so when somebody clicks on monkey grip button or selects its from the a3 list this will be what they say because they see a three by two grid they immediately know what they need to change if they want to change the three to a four that just changed it three to a four without having to think about whether it's the X or the Y Direction so if we were to give them the same default then they wouldn't be able to see it and then they would have to think like which direction is X which direction is Y which value do I want to change and this is why I give them distinct values finally the default for the size run again delete everything and there you can see your defaults and when we execute without any values it just uses those defaults and the same for the f3 menu there's one more step left and that is to get that redo panel we have the properties so blender knows what should hypothetically go in there it just doesn't know yet that we support that redo panel so let's tell blender that we do this is done through Bill options the default value is register and we have to add undo to it this will give us the final ingredient there you go now we can make them big and small and give them even invalid values so to make it pleasant to use for people we should really set limits to a slider so that it's all sensible values that you can select there fortunately this is again quite simple we can set a minimum let's set it to 1 because creating zero monkeys doesn't make sense and creating negative monkeys even less so let's start at one let's set the maximum to 10 for now we can do the same for the count Y and we can set the size 0 to minimum and the maximum let's set it to 1 and now we can drag and things are still nice and sane you can see that it already gets a little bit slower when these numbers increase and we still can't get to the 600 we had before even when I type 100 here it is cut off to the maximum so this is for blender has a soft limit the hard limit is what we said now that's the absolute limit of the value of the property whereas the soft limit is what the slider will do when you drag around so if you want to allow maximum values that are bigger than 10 or sizes that are bigger than 1 but still want these limits as the limit for the slider you can change the maximum into soft maximum the minimum that we have now really as minimum because creating zero monkeys doesn't make sense negative monkeys is impossible also creating a negatively sized monkey is impossible so let's change the maximum to soft now the dragging is still the same what we can set it to create much more monkeys then you would get with dragging now let's get back to that class declaration I will explain a little bit more about how classes work in an intuitive way I hope without going too much into technical details classes use a system called inheritance just like with people it's a a parent-child structure so in this case be PI types of operator is the parent and mesh ot Monken grid access the child if you ask a child a question that knows the answer to say you want to have a cookie the child will say yes immediately without asking the parent of course but if you ask about taxes then mom please help me out there because I don't know anything and then the child defers that question to the parent and this is the same way that classes work in Python roughly we could do without the BL options our child didn't know anything about it so Python asked the parent and when we want to have something different we can add the options to our child to our class and then that is asked first so that takes precedence over whatever the parent wants so we always have lucky children who gets all the cookies that want so before I end this video I have two more things that I want to tell you one again we look at the execute function you see that it gets a context parameter and this is pretty much like the context we've seen before it gives us context that object context taught seen context to adult selected objects all these things you've seen before in be pilot context it gets here as well but then localized specifically for this operator so as a general rule of thumb if you a function that gets a context use that context and don't use be PI dot context so if you want to do something with all the selected postpones in this execute function you would use contacts dot selected postpones another function and that is the second thing that i wanted to show you another function that gets context is the poll function and it's written in a bit weird way but just take it from me it works like that again you get a context in this function but instead of doing something like a name instead of performing an action this function is meant to check whether that action will be possible so this poll function is called by blender every time this operator is supposed to show up in a menu or as a button on a panel I can show you how this works right now it returns true which means that it is always allowed just as it was before and just as it was before it shows up here in the f3 menu when I change this to false it will never show up anywhere which is kind of useless let's tweak this to make it a bit more useful you can see here in the console we have autocomplete which makes sense in a Python console but that same operator does not work in the 3d viewport because the contacts is wrong this is also something we can do ourselves right now when I change this to true again the monkey grid operator also shows up in the context of the Python console and it will show up anywhere in blender which is not exactly the right way to go let's take another look at a variable inside that context context thought area gives you the area that is currently active in blenders using interface so in this case it will be the console but if the mouse is here and we pull up the mathri menu then all of a sudden it's 3d viewport that is active and here it would be the outliner so every area in blender has its own area type and we can use that in our poll function to make sure that it's only working in the area that we want it to work in one thing I don't really like is guesswork so we know now that the area type of the console is console but is it in 3d viewport is a 3d view 3d underscore view is a 3d viewport I don't know so let's make our script tell us instead I can just say print my area is context of area dot type and let's see what happens on the terminal where all these kind of prints are sent to you you see the console and immediately you see it being called my area is fewer 3d the one I do it here in the outliner my area is outliner if I do it here in the properties panel my areas properties so that way you can just use these print statements to know what you have to put where so we now we know which value to use for the 3d viewport so let's just do that if context dot area dot type it equals and view 3d then return true otherwise we can return false let's see how this works here it still shows up but here is no longer there and of course here and there now it only shows up where we want it to show up one final thing these kind of constructs I see them a lot also from experienced programmers it's more complex than necessary actually because this guy is already an expression that is true or false so basically what the code is saying is that if the value of this thing this selected expression if the value of that thing is true return true and if the value of that thing is false return false so that basically means return the value of this thing which you can of course write as this so that was it for this episode of scripting for artists if you have any questions or remarks please leave a comment down below and I will see you soon

Channel: Blender

Views: 26,085

Keywords: blender, b3d, blender 3d, 2.8, 2.80, blender 2.8, blender foundation, Scripting for Artists, tutorial, Blender Cloud

Id: xscQ9tcN4GI

Length: 22min 13sec (1333 seconds)

Published: Fri Apr 03 2020