Beginners Guide to Apophysis Scripting

Page 1 of 14 Beginners Guide to Apophysis Scripting I've seen a couple of Apophysis scripting resources before. Some seemed technical and geared towards people who knew how to program. Others were more of a reference of commands and what they could do, but didn't really walk a ner through how to use them. I'm not trying to take anything away from these resources. They are beneficial and serve a purpose. I'm glad that people put them together. But I have had countless comments on my scripts where people (a) assumed it was a script problem instead of a problem with their Apophysis plugins or paths or missing Functions.asc, or (b) were telling me that the wish that they could do what I did with scripts but didn't have a clue how to do it. That is who this tutorial is for. If you would like to be able to write a script or read and understand what one is doing, this tutorial is for you. Because I assume you don't know anything at all about programming, I'm going to be quite verbose and use a lot of analogies. My goal is to get you through the basics of a simple script. Once you have the basics, I'll write a sequel to this that will get into batch scripts, prompting for actions, and so forth. There is a caveat though to the no experience necessary idea. This tutorial assumes that you know how to use Apophysis and know how to change things in the Apophysis editor window. If you don't know what I mean by creating a new flame, adding a transform, X and Y coordinates, mater scale, and so forth, then me talking about changing those things without doing it manually isn't going to make a whole lot of sense. If you don't know Apophysis and Apophysis terms, there are several good tutorials out there. The Apophysis group at DeviantArt has a list of several. Searching the Internet for "apophysis tutorial" will also bring up a lot of resources for you. Once you understand the basics of how Apophysis works, then is the time to get into how to automate it. First, what is a script? Let me tell you what it is not. It's not programming. Sure, there are some particular words or commands like programming, but it is more of a macro. Knowing some programming helps, but I'm going to try to stay away from all those computer programming terms and put this in language that my somewhat-blonde daughter can understand. :) Think of a script as a list of instructions to do repetitive tasks. If I had to make 6-dozen identical cupcakes for my kid to take to school, how would it do it? I'd follow a recipe. That way no matter how many "batches" of cake batter I had to make, they would all be the same. Why? Because they all added the same amount of each of the ingredients in a particular order. A script is like that. It is a series of instructions that Apophysis can follow that produce a consistent result. Let's say that I want to make a flame that has two "triangles", the first with a spiral variation, the second with a diamond variation. Suppose I then add a final transform with some swirl variation. (Again, if none of that made sense, go through a Apophysis tutorial). This would be an easy task. I

Page 2 of 14 can do it in about ten mouse clicks. But if I wanted to make 100 of them (like my 6-dozen cupcakes), that would be 1,000 mouse clicks. It would be much simpler to automate that so that Apophysis would create those for me. Writing twenty or so lines of "instructions" would produce a lot faster and more accurate results than if I were to try to do it all manually. That is why we need and use scripts. Now, before I go into any kind of scripting commands, lets look at the parameters of the fractal that I described in the prior paragraph. I'm not trying to scare you. But when you read it, some terms should jump out at you as the same terms that Apophysis uses in it's interface. I've marked the "pallette" section of the parameters separately because we are not going to be creating gradients with scripts. Creation of gradients is a whole different animal. We want to concentrate on the blue section. <flame name="starter Flame" version="apophysis 2.07 beta" size="547 425" center="0 0" scale="136.75" oversample="1" filter="0.5" quality="50" background="0 0 0" brightness="4" gamma="4" > <xform weight="0.5" color="0" spiral="1" coefs="1 0 0 1 0 0" /> <xform weight="0.5" color="0" diamond="1" coefs="1 0 0 1 0 0" /> <finalxform color="0" symmetry="1" swirl="1" coefs="1 0 0 1 0 0" /> <palette count="256" format="rgb"> E0612CCD3B3BBA164BB40E54AE065EB21C6EB6327EB13C95 AC47AD5F6AB94959B23448AB412F7C4F164D522A57563E62 14678F1261A0115BB20B52B30549B40B41AC113AA41A2D8C 3033A62F42A84E5DB06D78B88F71B8B26BB9A04EAE8F32A4 5A3698434AA32C5FAE1F8AA312B5980DC59408D590279082 3D677F3251BB2C6FD2268DEA2A88E82E84E72C77D02B6ABA 1061BA1654B51D48B12351B42A5BB72D60B33066B0366AB5 2969B30C6ECF226CCC386AC94B72CD5F7AD19387C7B397C0 AE93BE926AC47741CA6733CA5825CA5819C6580DC26006C7 4E07CD6117CC7015DB8013EA930BEDA603F0BD08F7A820E4 8745C37454C36164C36256C26448C15135AC4435AA3829A8 3234BB3255C9214FBF104AB5183CB5202EB52D239D3729B0 3372B92D88B9289EBA3092B33886AD4D5BC4434BAE313EC0 2133C54B0CF14F15F3531EF56736F26B16C96A17B16E086E 870660AD0559D40553D70554DB0656D30A4EC9165ACB1979 DE3473CE5487BF6392B0739DB089C29D7DBC8252B6752E94 41046B680A5990114896114B9D114E87386579207274187D 69299B6733A2583BA64A43AB3451B53857C32841B7254FB1 2256DE285FE92F68F54560EF4C34C84E12CA5D13C26D18BE 8618D3BD0F94B01084A41275821A93891EA26D24BB723ECF 7050CF6F4AC96F45C37D43BCA760BEB164CAA169CAAA70BD BD60A79C3874AA1454A80560AC106392177F73288F693796 4130B2382DBD2F2BC83411CF4617C74521BF5317B5390897 38128B56168E5634A2301FA91209BA1213CD1112C21621B7 1C38BD0F3CBB0143B30D1E8631218E5C1E819E1E7FC95586 DC9169E3A653E1A35AB0ABAF85B8995A8CBD3A92C4397BD1 3A59C51E5FBB1E5BB6203DBF0E4BC81A49FB0E1AEA2E3ACE 5260CB5666C83D93B445A6B64995AF538AC07F74C09D65C8 865BCE7E65CD6667C45C75C57284C6879DC6629E9F3CA789 61868E71469F904F3DDA713AEA7F21DA7C3CCF8F37D99F3C E4944DC14672B21F6F9551828877705BC36C4AE6850DCA86 3BAFAE20A3AD2EABAD3DB4AE75B59FAEB691A59C629C8333 </palette> </flame>

Page 3 of 14 Think of this as a list of ingredients in a recipe. The recipe doesn't teach cooking, but if you know cooking, you can follow the recipe. In the same way, this "list of ingredients" isn't a tutorial telling you how to open Apophysis and create this particular flame. Think of a script as something between a list of ingredients and instructions that tell you to actually crack open the eggs and add the contents of the egg shell to your cupcake and not the entire egg, shell and all. Anyway, think back to the ten mouse clicks that I mentioned. Those were not just mouse clicks. They were instructions to Apophysis to do something. The little icon that you click on to do something is nothing more than a graphical interface to a command in the background. The exact same thing can be done with words. Those words, in a certain order, is what a script does. So let's look at the parameters or "ingredients" for our simple fractal. Ignore the first line as it is typically rendering instructions, not the "ingredients" that we want to focus on. You can probably guess that "xform" is short for "transform" and refers to what some people refer to as "triangles". The six numbers in the "coefs" section refer to the X, Y, and O sections that you see in the triangle tab of the Apophysis editor. Weight is on the Transform tab, color and symmetry on the Colors tab. This is basically the stored values of all the things in the Apophysis editor window that creates the flame. It doesn't include that huge list of variables that you see in the Variables tab. Why? They are not used because we are not using any of the variations that use those variations. It only includes the "ingredients" that we need for our recipe, not the entire contents of our pantry. The fact that I have 3- cups of rice in my pantry is irrelevant to my cupcake recipe because "rice" isn't one of the ingredients. Scripts are like that. If all I am doing is adding a final transform to create a "marble", I don't need to include all the other things in fractal in my list of instructions. All I need is my commands for the final transform. OK. If I haven't scared you off yet, lets get into a bit of scripting. Remember our ten mouse clicks and our sample flame? We are going to use that. Instead of mouse clicks though, we are going to write a script that will create that fractal for us! This is what we are going to do. We are going to look at what goes on behind the scenes when you click on each of those items, but do it in scripting "language". For each mouse click, the following indented lines will tell you the script command that does the same thing. Once we get through our "clicks", we will assemble it all in a finished script. First, let's start with our mouse clicks.

Page 4 of 14 Assuming that you have Apophysis open, click the editor icon click the new blank flame icon double-click the linear variation to set it to 0 double-click the spiral variation to set it to 1 click the icon at the top to add a new "triangle" double-click the linear variation to set it to 0 double-click the diamond variation to set it to 1 click on the icon to add a final transform double-click the linear variation to set it to 0 double-click the swirl variation to set it to 1 Depending on where your triangles are placed, you should have something that looks like this: If your's is a bit different, that's OK. As long as you have something that is a combination of spiral and diamond with a final swirl, you're OK. That is all we are going after. In fact, if your fractal is a bit different, that is a good thing! Who wants a script that produces the exact same fractal each and every time? If I want to re-create the same thing, I'll just re-render the same parameters. This is where our analogy departs slightly from our cupcakes. We want our fractals and cupcakes to have a little bit of personality and slight differences. The effect of our script needs to be consistent, but the outcome doesn't need to be identical. OK. Now that we've followed a recipe of mouse clicks, lets translate our clicks into commands. To do that, I'll put the clicks on one side and the commands on the other.

Page 5 of 14 click the editor icon We don't really need to do anything here. Using a script, by default, means that you are going to be editing something click the new blank flame icon Clear double-click the linear variation to set it to 0 When you create a blank flame in the editor, it defaults to having one transform for you. We need to manually create that in the script before turning off linear, so we do that with two commands: double-click the spiral variation to set it to 1 Transform.spiral := 1; click the icon at the top to add a new "triangle" double-click the linear variation to set it to 0 double-click the diamond variation to set it to 1 Transform.diamond := 1; click the icon at the top to add a final transform We can't just add a new transform and expect Apophysis to know it is to be the last one, so we specifically create it as the last one with the following: SetActiveTransform(transforms) double-click the linear variation to set it to 0 double-click the swirl variation to set it to 1 Transform.swirl := 1; That's not too scary, is it? There are some other things that we need to do with a script though. When you are in the editor, it knows what transform you are working with because you have it selected. With the script, you have to tell it what actions or commands belong with which transform. You can't just say: Transform.diamond := 1; With the script, you have to tell it that these events are to be done on the transform that you just created or added as follows:

Page 6 of 14 Transform.diamond := 1; Also, with the final transform, you will notice in our table that we didn't do anything but add another transform in a way to tell Apophysis that it was the last one. We need to tell Apophysis that that last transform is supposed to be treated as a Final Transform. We do that with the command Flame.FinalXformEnabled := true. So, adding all these commands together, let's create a simple script: Clear; Transform.spiral := 1; Transform.diamond := 1; SetActiveTransform(transforms) with Transform do Transform.swirl := 1; Flame.FinalXformEnabled := true; This is a fully functional script. It works. It produces something that should be just like the image it was patterned from. If it is a little different from our original pattern, that's OK. When you get into the scripting a bit more, you can make it as identical or as different as you want. As things stand in our script right now, we haven't addressed the location or rotation of our transforms. That may produce a

Page 7 of 14 different result if your locations are slightly different from my own. Before we go any further with commands though, let me talk a bit about the format of the script. This isn't as much functional as it is cosmetic. It makes things easier to read and understand. Now I'll be the first to say that I don't do this in all of my scripts. I know I should, but I'm lazy. :) The first thing I want to point out is how I indented the commands that set the transform variations to either 1 or 0. You don't have to do this, but when you are in a section of commands like this where you have a and end, it makes it easier to understand. This is particularly the case if you have a and end section inside another and end section. For example, I could have our script above loop through an entire flame pack and do these modifications in a batch mode. By indenting what the batch is doing and then further indenting what each transform is doing, it makes things much easier to go back later and figure out. The second thing that you should do with your scripts is comments. Comments can be done two different ways. //This is a comment on a single line. It starts with '//' and can have anything after it as long as I don't hit the enter on my keyboard and start a new line. {this however is an example of a comment that stretches over many lines in the script. It is surrounded by brackets} By using this technique, we can do something like the following: //This is our second transform the diamond one Transform.diamond := 1; As we continue to develop our script, I'll be adding these comments in to make things a bit more clear. I'll also, as our script grows, signify in red the things that we are adding to the script from the prior example.

Page 8 of 14 Also note that I end the instructions with a semicolon. This tells Apophysis that the command is complete. It treats something after the semicolon as a new thing. I like to get in the habit of doing this because it makes it easier to add a comment to a command. You could do something like: Flame.FinalXformEnabled := true; //this adds the final transform. You couldn't put the comment first followed by the command because anything after the // would be considered a comment. In fact, that is the perfect way to disable part of a script to test something. If you took Clear at the top of a script and changed it to //Clear it would not start a new fractal, but add all the stuff that is in the script to an existing one. A lot of the scripts that I have done are nothing more than combinations of two scripts like that. I'll frequently remove the Clear from the top of a new script and run it on a fractal of a specific type to see what happens. Before we get into general flame manipulation, I want to talk some more about how to do more things with our transforms. As you may have noticed, to set the variation of a transform, you use the syntax of Transform.VariationName := value. These values can be positive or negative. If they are decimal values less than zero, they need to be stated as 0.75 though, not just.75. If you want a negative value, you would put something like -1 or -3.14. You can do this with more than just variations though. And this is where things get more interesting. You can use the same kind of syntax for variables associated with variations. Instead of Transform.swirl := 1; in our final transform, you can use a variation that has associated variables in the variable tab. You could, for example, say Transform.blob := 1; Transform.blob_low := 0.96 Transform.blob_high := 1.24 Blob_low and Blob_high are the two variables associated with Blob. This sequence of instructions would be identical to me double-clicking the linear to set it to 0, double-clicking the blob to set it to 1, and then going to the variations tab and inserting these to values for the ones that are already there. Basically, when you see any variation that is in the shaded portion of the list, it is a good idea to see if there are associated variables that go along with it. It may be a plugin with no variables, but check to see. And if the variables exist, you can use them in your script.

Page 9 of 14 We've talked about setting these variations and variables to a set number. That can be important. You might, for example, do the following for a final transform: Transform.juliascope := 0.625; Transform.juliascope_power := 2; Transform.juliascope_dist := 1; This gives us an image that looks like this: And, while you can't really tell from this example because of the other variations that we are using, that combination in a final transforms is what produces the heart shape in most (if not all) of my heart scripts. (BTW, I played the the gradient a bit as well, your coloring may be different.) Here is what our script looks like so far with our added comments and our modified final transform: Clear; //Begins a new flame //Create the first transform Transform.spiral := 1; //Add the second transform Transform.diamond := 1; //Add the final transform

Page 10 of 14 SetActiveTransform(transforms) with Transform do Transform.linear := 0 // Transform.swirl := 1; <----- Note that this is now commented out Transform.juliascope := 0.625; Transform.juliascope_power := 2; Transform.juliascope_dist := 1; Flame.FinalXformEnabled := true; //this sets the final transform Ready to go on and make this slightly more interesting? We don't have to set absolute values in our scripts. We can set random ones. When you are creating a script from scratch, it is often required to make something random in order to get some variations out of it. When you use random instead of a number, random comes up with some decimal number between 0 and 1. It's like a percent. It could be 1%, 85%, or something like 0.038%. It's random. Right now, our script produces the same result every time. If we want some variation, we can do something like change the line that says Transform.juliascope_dist := 1; to Transform.juliascope_dist := random; Then, every time we ran our script, we would get the same effect, but a slightly different composition. If we want to really mix things up, we could say something like Transform.juliascope_dist := random*3; This multiplies our random number by 3 and would conceivably give us a value of anywhere between 0 and 2.9999999999... as our juliascope_dist. Here is an example. See how our ears have grown? Yet some samples have hardly any at all. It is this kind of variation that we look for in a good script. There is, however, a way to get additional randomness. I'm speaking of mixing up the gradient as well. In order to have the gradient randomized as well, we can start each flame out as a new random one.

Page 11 of 14 Ever notice that when you create a random batch, that each flame in that batch has a new and different gradient? Well we can steal the command from the script that creates random batches and use it ourselves. That command is RandomFlame(0). Add that to the top of your script as the very first line and then run it a few times. This is what your script should look like now: RandomFlame(0) Clear; //Begins a new flame //Create the first transform Transform.spiral := 1; //Add the second transform Transform.diamond := 1; //Add the final transform SetActiveTransform(transforms) with Transform do Transform.linear := 0 // Transform.swirl := 1; Transform.juliascope := 0.625; Transform.juliascope_power := 2; Transform.juliascope_dist := random*3;

Page 12 of 14 Flame.FinalXformEnabled := true; //this sets the final transform There are other things going on with transforms other than their variations and variables though. We also have things like weight, color, symmentry, and the ever important coefs or location of our triangles. For most of these, you set them the same way as you do other variables In our sample flame that we started with, we can say things like Transform.weight := 0.5 or Transform.color := 0 or even Transform.color := random. Things work a bit differently though in the setting of the transform location. Those two columns of numbers on the transform tab in the editor are lettered A through F. If you want to specify them in a script, you would say: Transform.A := 1; Transform.B := 0; Transform.C := 0; Transform.D := 1; Transform.E := 0; Transform.F := 0; You can randomize these as well. But another way to shake things up a bit to to rotate the transform. Rotate(45.0);, as a line in your transform section (that indented section between the and end ) would rotate your transform by 45 degrees. Since we have 360 degrees in a circle, any number between 0 and 360 would work. Or, you guessed it, you could randomize it with Rotate(360*random); Rotation is a good transition into the discussion of how to manipulate the entire flame. You can rotate the entire flame with the command RotateFlame(360*random); I tend to do all my transform specific things first and then group all my general flame modifications at the end. Besides rotating the flame, here are some examples of what you can do that would otherwise be done in the Apophysis Adjust window. They are pretty self-explanatory, so I will just list them: Flame.X := value; Flame.Y := value; Flame.Zoom := value; Flame.Scale := value; Gamma := value; Brightness := value; Vibrancy := value; As with other values that we have set, you can set these to a specific number or randomize it a bit. The first four of these have to do with the position of the fractal in your window. But, depending on what

Page 13 of 14 you have going on in your script, you may not know exactly what X and Y coordinate centers your flame or what master scale setting enlarges it, but not the point that it overflows the borders of your window. Luckily, there is a command that helps us with this. CalculateScale; Add that to the very bottom of your script and try it. Here is an example of our output now: As you can see, our new CalculateScale command does a pretty good job of moving our eight-sided star thing to the bottom so that we get plenty of the ears or whatever that is coming from the top. It's not perfect, but it's better than it was. Here is what our completed script looks like: RandomFlame(0) Clear; //Begins a new flame //Create the first transform Transform.spiral := 1; //Add the second transform Transform.diamond := 1; //Add the final transform SetActiveTransform(transforms) with Transform do

Page 14 of 14 Transform.linear := 0 // Transform.swirl := 1; Transform.juliascope := 0.625; Transform.juliascope_power := 2; Transform.juliascope_dist := random*3; Flame.FinalXformEnabled := true; //this sets the final transform CalculateScale ; ========================================================================= That about wraps up the ners level guide to simple scripts. Here is what I would suggest. Get a script that you really like and make a copy of it. Start playing with the values and variations in it. Randomize some things. Don't be afraid that you might break it. You still have your original. Once you get comfortable with changing someone else's, start creating some new scripts by copying the final transform from one script and placing it in another. Once you are comfortable with that, maybe write one from scratch. If you don't know what to start with, do like we did here. Create or load a flame and look at all the settings in the Edit window. If you don't know which ones are used and which ones are not, look at the parameters. The parameters will only contain the necessary elements to create the fractal. If you get really, really stuck, don't be afraid to ask questions. The Apophysis chat room at http://chat.deviantart.com/chat/apophysis is an excellent place to ask for help. If you can't get help there, join the Apophysis mailing list by sending an email to apophysis-subscribe@lists.fractalus.com and ask your questions there. You can always drop me a note on my DeviantArt page (http://djeaton3162.deviantart.com) or drop me an email at daniel@my-fractals.com and I'll be glad to assist you if I can. Finally, if you want to get into the Apophysis Scripting Reference Manual and see some more advanced things, check out http://apophysis.wikispaces.com/apo+script+reference+manual. My intention is to do a sequel to this tutorial. It will, I hope, get into how to do things with an entire batch of flames, how to prompt for something (like Do you want to add Blur? ) and act accordingly, how to set some of the rendering options and render form inside a script, and how to show the progress of what is going on in a script. It will also cover changing the overall Apophysis options like batch size, prefix, the sequential number being used for new batches, and so forth. It may take me a couple of days, but stay tuned for the sequel. Daniel Eaton daniel@my-fractals.com