fragstat and cookie

UNSUPPORTED SOFTWARE: USE AT OWN RISK

Using FRAGSTAT with COOKIE and DOCOOKIE

Here's what's on this page:

Introduction
Cookie command table
Extended example
Getting the software
Credits

Introduction

This document describes how to run fragstat on several parts of your image.

For example, you have mapped the locations of nests on an image, and wish to compute fragmentation statistics on a circular buffer around each nest.

COOKIE cuts out subimages from your Idrisi image, according to commands you supply in a cutter file. You can then run fragstat on these subimages.
DOCOOKIE runs COOKIE on your image, and generates a batch file that will run FRAGSTAT on each image created by the cutter file. Output is sent to the same file for each subimage.
Graphically:

The image files will have '.img' extensions and are in Idrisi format. They must
be accompanied by '.doc' files giving the coordinates of the image.

Commands

Here are the commands that COOKIE understands:

Task	Command	Parameters	Description
set subimage bounds	b	left top right bottom	Defines a window on the original image. Any subsequent commands will be clipped to this window. The subimage will be the size and shape of this window. If you don't set bounds, they are automatically calculated for each subimage, and will be just large enough to hold the shapes you give commands for (but no larger than the original image).
copy rectangle from image	r	left top right bottom	Copy a rectangle from the original image to the subimage. Pixel colours are copied as is. If bounds have been set, only that part of the rectangle within bounds will be copied.
copy circle from image	c	x y radius	Copy a circle from the original image to the subimage. The circle is centred at (x,y) and has the given radius. Pixel outside the circle are left unchanged in the subimage. If bounds have been set, only that part of the circle within bounds will be copied.
copy patch from image	p	x y	Copy the (FRAGSTAT-style) patch containing the point (x,y) from the original image to the subimage. The patch will be the same colour as the original. Pixels outside the patch are left unchanged in the subimage.
fill rectangle in subimage	fr	left top right bottom colour	Fill a rectangle in the subimage with pixels of the given colour.
fill circle in subimage	fc	x y radius value	Fill a circle in the subimage with pixels of the given colour.
fill outside circle in subimage	fcc	x y radius value	Fill outside a circle in the subimage with pixels of the given colour. All pixels not within the circle are coloured.
fill patch in subimage	fp	x y value	Copies the patch containing point (x,y) from the original image to the subimage, changing the patch colour to the given value.
save subimage	w	filename	Save the subimage in fragstat format to the given file. Subsequent commands create a new subimage.
save subimage and keep	wk	filename	Save the subimage in fragstat format to the given file. Subsequent commands continue operating on this subimage.
save subimage as Windows bitmap	wb	filename	Save the subimage as a Windows bitmap in the given file. Subsequent commands create a new subimage.
save subimage as Windows bitmap and keep	wbk	filename	Save the subimage as a Windows bitmap in the given file. Subsequent commands continue operating on this subimage.

All dimensions are in pixels, with (0,0) at the top left of the original image. Commands operate on the same subimage until a save command without the keep option.

Example:

Suppose demo.doc is:

file title : demo (made by cookie from test2)

data type : byte

file type : binary

columns : 175

rows : 175

ref. system : plane

ref. units : m

unit dist. : 2.000000

min. X : 100.000000

max. X : 450.000000

min. Y : 100.000000

max. Y : 450.000000

pos'n error : unknown

resolution : unknown

min. value : 0

max. value : 255

value units : unspecified

value error : unknown

flag value : none

flag def'n : none

legend cats : 0

Then here are some examples, created by running:

docookie demo.img democut.txt 0

Commands from democut.txt and the images they create. (All commands were in the same file.)	Explanation
Original image in file demo.img	image coordinates: left: 100 right: 450 top: 450 bottom: 100
c 320 240 200 wk demo1	Copy a circle from the original image, setting the background to black (the colour 0) as specified above. Using wbk instead of wb means subsequent commands will continue to operate on this subimage.
fc 320 240 100 5 wk demo2	Fill a circle with colour 5 (blue-green).
r 280 200 360 280 w demo3	Copy a rectangle from the original image.
b 100 100 400 400 p 320 240 wk demo4	This is a new subimage because the previous command was wb, not wbk. Set subimage bounds to a square. Copy the patch containing point (320, 240) from the original image, preserving its colour. Patches are defined just as in FRAGSTAT. (If you learn to use cookie.exe directly, you can specify the -n option that tells it not to search diagonally for cells belonging to the same patch. FRAGSTAT also has this option.)
p 200 350 wk demo5	Copy another patch.
fp 150 150 16 wk demo6	Fill in the patch containing point (150, 150) with the colour 16 (bright red). The shape of the region being filled comes from the original image, not the current subimage; that's why the black borders around the orange blots remain.
fcc 320 240 150 5 w demo7	Fill outside the circle centred at (240, 150) with radius 150 using the colour 5 (blue-green).

Note: to generate viewable images for this web page, I used the wb and wbk commands for cookie to create Windows bitmap (.bmp) files, which I then converted to JPEG (.jpg) files. FRAGSTAT can't read bitmap files; use the w and wk commands to create FRAGSTAT-readable Idrisi image files.

This command also generated the file dofrag.bat, which you can run by typing dofrag at the DOS command prompt.
Here it is:

del fragout.full

del fragout.class

del fragout.lnd

del fragout.patch

fragstat demo1 fragout 1 5 6 $ $ 255 10 $ 2 $ 0 100 y y y

fragstat demo2 fragout 1 5 6 $ $ 255 10 $ 2 $ 0 100 y y y

fragstat demo3 fragout 1 5 6 $ $ 255 10 $ 2 $ 0 100 y y y

fragstat demo4 fragout 1 5 6 $ $ 255 10 $ 2 $ 0 100 y y y

fragstat demo5 fragout 1 5 6 $ $ 255 10 $ 2 $ 0 100 y y y

fragstat demo6 fragout 1 5 6 $ $ 255 10 $ 2 $ 0 100 y y y

fragstat demo7 fragout 1 5 6 $ $ 255 10 $ 2 $ 0 100 y y y

All output from FRAGSTAT will end up in the four files fragout.* which are first deleted.
Consult the FRAGSTAT documentation for more information on its parameters - you can edit
these in dofrag.bat before running it if you want different options.

Getting the software:

The source code for (fast) fragstat and cookie is available at http://www2.biology.ualberta.ca/jbrzusto/ftp/fragstat/fragsrc.zip I have rewritten much of the fragstat code in this distribution to use run-length encoding for better speed and memory efficiency. Currently, this only works for Idrisi images.
For DOS/Windows users, because these "operating systems" don't come with development tools, the executables (requiring a '386 or better) are available at http://www2.biology.ualberta.ca/jbrzusto/ftp/fragstat/fragzip.exe
- Download this file using your web-browser or anonymous FTP
- save it in a directory called fragstat, or something
- run fragzip from the DOS prompt after switching to that directory
- delete fragzip.exe once the files have been extracted

Credits:

FRAGSTATS was originally written by Barbara Marks and Kevin McGarigle (the current maintainer).
The FRAGSTATS homepage is here.
Cookie requires (and the DOS binary distribution includes) gawk, by the Free Software Foundation (www.fsf.org). It is freely redistributable in binary and source (ftp://ftp.cs.ubc.ca/mirror2/gnu/gawk-3.0.3.tar.gz) form, under the terms of the Gnu Public Licence (http://www.fsf.org/copyleft/gpl.html). For why software should be free, see
http://www.fsf.org/philosophy/why-free.html

This page, cookie and docookie are by John Brzustowski (junkjbrzusto@ualberta.cacaca but removing the obvious parts), who also substantially rewrote fragstat it to use run-length encoding, for substantial time and memory savings. (e.g. a 9500 x 13000 image, ~118 Mbytes in size, will run on a DOS box with 64 Mbytes of RAM without swapping to disk.) You are free to use, redistribute, and modify them. Please direct any questions, complaints, or comments about this page or the programs in the distribution to John.

cookie.html 17 November, 2000