Getting started scripting in GIMP

First, read the ScriptFu tutorial, starting with chapter 2 trough the end of chapter 3. Great, no problem.

Now, make sure you have gimp, I roll on a Mac so I had to go here. But, you probably already did that, good.

Next, go get yourself tons of examples, other scrips. Find some stuff that you might want to do, and work your way through their code. Modify it to do something new!

Here are some things to remember about Scheme:

• Parenthesis are important... use just the right amount, they mean something
  
• You put the operator first then the operands, all inside parens:
  
  (+ a b) ; same as a+b
  
  
• Call a function using parens:
  
  (gimp-image-new 512 512 0) ; creates a new image 512x512 in RGB mode (0)
  
  
• You can create variables two ways:
  
  
  
  • (define x 1) ; use x where you like
    
  • (let* ((x 1)) ...) ; x only exists within the (let* ... ) parens
    
  
  
• Set the value of a variable:
  (set! x 10) ; sets x=10, assuming x was defined earlier
  
• Create a function like this:
  

  
        (define (function-name parameters...)
           ... do stuff ...
           ; the last expression in a function is it's return value
        )
      

  
  
• Sometimes things are lists, especially function return values.
  
  
  
  • Use car to get the first element of the list
    (define x (car (gimp-image-new 512 512 0) ) ); puts the image id in x
    
  • Use cdr go get the rest of the list
    
  
  
• For-loops are a little strange. To do something 10 times it goes like this:
  

  
        (let loop ((i 0))           ; "loop" can be any name
          (if (not (= i 10))        ; test to see if you've already done it 10 times
            (begin                  ; start a block of instructions
               ... do something ... ; do your work here
               (loop (+ i 1))       ; go back to the top, increment i 
                                    ;   ... i.e. call loop with i+1
            )
          ) 
        )
      

  
  
• Leave comments, anything after a ";" is a comment... English is also a nice language to use
  

   
    (somefunction x y)  ; this is a comment, should describe what you are doing
      

  
  
• Edit your script as a script! You need to do the following:
  
  
  
  • Create a text file, on windows use Notepad for example.
    
  • The filename convention is script-fu-yourscriptname
    
  • Add to your script file the registration function. This will tell gimp what function to call. Below is an example registration, note that SF-BLAH stuff creates a user interface, so these items depend on the script, and are optional.
    

    
    (script-fu-register
        "script-fu-myscript"                        ;func name
        "Some Script I wrote"                       ;menu label
        "This Script does stuff with things\
         to make widgets of ambiguous\
         utility."                                  ;description "\" means keep newline 
        "Dr. Joe"                                   ;author
        "copyright 2010, JMK LLC Inc.               ;copyright notice
        "Stardate 2010.2"                           ;date created
        ""                                          ;image type that the script works on
        SF-STRING      "Text"          "Text Box"   ;a string variable
        SF-FONT        "Font"          "Charter"    ;a font variable
        SF-ADJUSTMENT  "Font size"     '(50 1 1000 1 10 0 1)
                                                    ;a spin-button
        SF-COLOR       "Color"         '(0 0 0)     ;color variable
      )
      (script-fu-menu-register "script-fu-text-box" "/IFDM/MyScript")
    

    
    
    
  • Now put the text file in the gimp script directory. This is in your "home" directory, look for a file ".gimp-2.2/scripts". Yes the file starts with a "."
    
  • To make it show up, go to ->Script-Fu->Refresh-Scripts.
    
  • Now you can run it by finding your script in the right menu. The location of the script depends on what you put for "script-fu-menu-register", the function right after the registration function.
    
  • Of course, check the documentation and tutorials for more info
    
  
  
  
• There are many other nice things to learn about Scheme, but this will get us started...
  

Try some commands now. In gimp goto: Filters->Script-Fu->Console. This will open a command window that will allow you to test scripts. Now try this:

  (define mynewimage (gimp-image-new 512 512 0)) 

... hit enter. The window should show your command followed by some number in parens (1) for example. This is the image's ID and it's stored in the variable mynewimage. Now type:

  (gimp-display-new (car mynewimage))

... this should show a new image in gimp. We needed the (car mynewimage) because the image ID was actually inside a list, with just one element in it, the ID itself.

There is no need to memorize the functions that gimp provides. If you click on the "browse" button next to the text-entry-field in the console, it will produce a gimp function browser, so you can find the function you want AND its documentation.