I will do my best to explain some things.

Simple commands work, using 'Apply' from the Procedure Browser screen, like;

=> (gimp-version) ("2.2.8")

Note that the return value is a LIST containing the string "2.2.8". All PDB functions return a LIST of items even if that list only contains one item (indeed, the majority of the query-type commands return a one-item list; requiring '(car ret-value)' to access the item itself).

From there on, I have difficulty understanding the

Return Values, and the requirements for the function parameters suchs as; CHANNELS, DRAWABLE.

IMAGEs, CHANNELs, DRAWABLEs, LAYERs, DISPLAYs, et cetera are all integer IDs which are unique within their group (you might have an IMAGE with an ID of "3" and LAYER with an ID of "3", but you will never have two layers with an ID of "3" at the same time). They would all seem to be non-negative integers greater than zero (I think it is a fair assumption that this will always be the case).

DRAWABLEs are a superset of LAYERs, CHANNELs, and LAYERMASKS.

A LAYER is an arbitrary-sized bitmap that can be either RGB or GRAYSCALE. By arbitrary-sized, I mean that its dimensions are not bound by the image dimensions (nor is its position, a LAYER can be completely "outside" the image).

A CHANNEL is a fixed-sized, GRAYSCALE bitmap whose dimensions are fixed and whose position is anchored. If the CHANNEL is a LAYERMASK then the size and position are the same as the the LAYER to which it belongs. Otherwise, the CHANNEL's size and dimensions are the same as the IMAGE's.

These identification numbers are what is expected (and what are returned) when you see them referenced in the PDB. They are simple integers (i.e., they are NOT pointers or structures) and you can specify them explicitly as such in the Script-fu console. For example:

(gimp-image-get-active-layer 1)

Will return the active layer for IMAGE "1" (the IMAGE-ID, "1", is assigned to the first image you open with the GIMP)

Like in the following, which the Procedure Browser says should be;
num_images INT32 The number of Images open image_ids INT32ARRAY The list of images currently open

=> (gimp-image-list) (1 #(2)#1"02")

The LIST returned contains two items: the second item is an array of active IMAGE-IDs and the first item is the size of the array. To access an entry in the array, use 'aref':

(define all-images (gimp-image-list)) (define first-image (aref (cadr all-images) 0)) (define last-image (aref (cadr all-images) (- (car all-images) 1))

The value of an IMAGE-ID is appended to the filename in the window's titlebar; which makes interaction from within the console easier. For example, "Untitled.png-#1.0" in the titlebar indicates that the IMAGE-ID is "1" (the "0" indicates the DISPLAY-ID, and will be zero unless you have more than one view open for the same image).

If someone could give me an example of using the Script-FU Console to work gimp-drawable-set-pixel that would be great.

In order to use 'gimp-drawable-set-pixel', you must create a byte-array for the pixel's color. This can be accomplished with the following function:
(define (color-as-bytes r g b a)
(let* ((color (cons-array 4 'byte))) (aset color 0 r)
(aset color 1 g)
(aset color 2 b)
(aset color 3 a))
color
)
)

Once that function is defined (and assuming that my description of drawables wasn't completely unfathomable), you would use the following command to set a pixel on an RGB drawable:

(gimp-drawable-set-pixel drawable 1 1 4 (color-as-bytes red blue green alpha))

Note that you will see no change in the display; even if you were to perform a 'gimp-displays-flush'. The set-pixel command does not register with the UNDO history (it might be problematic to UNDO a few million pixel ops) and therefore you must manually force an update to the display to see the change (I would recommend hiding-and-unhiding the layer).

-------- "It is amazing what you can accomplish if you do not care who gets the credit." -- Harry S. Truman

In my response, I had a cut-n-paste error in the last code-segment. The line:

(gimp-drawable-set-pixel drawable 1 1 4 (color-as-bytes red blue green alpha))

should be changed to:

(gimp-drawable-set-pixel drawable x-coord y-coord 4 (color-as-bytes red blue green alpha))

The "4" in the line refers to the bytes-per-pixel and would be "2" if the drawable were grayscale. A '(grayscale-as-bytes value alpha)' function should then be defined to create a 2-byte array.

-------- "It is amazing what you can accomplish if you do not care who gets the credit." -- Harry S. Truman

Hi,

On Sat, 2007-01-13 at 20:33 -0800, Saul Goode wrote:

Note that you will see no change in the display; even if you were to perform a 'gimp-displays-flush'. The set-pixel command does not register with the UNDO history (it might be problematic to UNDO a few million pixel ops) and therefore you must manually force an update to the display to see the change (I would recommend hiding-and-unhiding the layer).

If that is true, then this is a bug and needs to be fixed. Can you provide a test script that illustrates the problem?

Sven

Sven Neuman wrote:

On Sat, 2007-01-13 at 20:33 -0800, Saul Goode wrote:

Note that you will see no change in the display; even if you were to perform a 'gimp-displays-flush'.

If that is true, then this is a bug and needs to be fixed. Can you provide a test script that illustrates the problem?

Step #1: Create a new image with a white background (any size will do) and zoom in to the upper left corner.

Step #2: Open the Script-fu console and enter the following commands (the number "1" in the first line assumes the new image is the first one created after opening the GIMP; substitute the appropriate image-IDnum from the window's titlebar if this is not the case):

(define image 1) (define layer (car (gimp-image-get-active-layer image))) (gimp-drawable-set-pixel layer 1 1 3 (cons-array 3 'byte))

Note that at this point, the pixel at location x=1, y=1 has "internally" been painted BLACK ('cons-array' initializes to [0,0,0]) but the display has not been updated.

Step #3: Enter the following line in the console:

(gimp-displays-flush)

Note that the display is not updated -- this is somewhat anomalous (but then Script-fu is not often used to paint on a pixel-by-pixel basis).

Step #4: Hide and then unhide the layer by toggling its "eyeball" in the Layers window. At this point the projection is updated to reflect that the pixel at [1,1] has been painted black.

-------- "It is amazing what you can accomplish if you do not care who gets the credit." -- Harry S. Truman

Adam wrote:

Like in the following, which the Procedure Browser says should be;
num_images INT32 The number of Images open image_ids INT32ARRAY The list of images currently open

=> (gimp-image-list) (1 #(2)#1"02")

so, #(2)#1"02"
is a single entry array of the image ID ? How should I interpret this sequence ?

Start by ignoring everything between the two close parentheses. There appears to be a bug in the output from the 2.2 version of GIMP. Using the current development version of GIMP I opened two files and asked for the image list. The result was
(2 #( 2 1 ))

The easy way to get the image ID when you need it as an argument for a command you want to run from the console mode is to look at the title bar of the image windows. Regardless of the file name, the filename (or the word 'Untitled' if it is a new image) shown in the title bar has text of the form "-x.y" at the end. The x part is the number that would be used as the image ID for that image.

So I try another command;
=> (gimp-image-height image)
ERROR: unbound variable (errobj image)

You need to use the actual image ID (ie. number) in the call or define image and set it to the desired number before you attempt to use it in a call to a GIMP function.

Hi,

On Sun, 2007-01-14 at 12:24 -0800, Saul Goode wrote:

(define image 1)
(define layer (car (gimp-image-get-active-layer image))) (gimp-drawable-set-pixel layer 1 1 3 (cons-array 3 'byte))

Note that at this point, the pixel at location x=1, y=1 has "internally" been painted BLACK ('cons-array' initializes to [0,0,0]) but the display has not been updated.

You also need to call gimp-drawable-update (and of course gimp-displays-flush).

Sven