Home
-> User's Manual -> Technology Diagram-> Macro Language

Pac-n-Zoom® Macro Documentation

Date: 11/30/11
Authors: Brent C. Dowd, Bernard Alala, and Joe Doll


Commands    -    A list of macro commands and their syntax

Conditional Opcodes    -    A table of opcodes used in conditional statments

Description    -    The description of a Pac-n-Zoom macro

FILENAME_LIST    -    Some comments on a list of file names

Macro Programming Rules    -    Some programming rules

Reserved Variables    -    Variable names that are already used

Variables    -    The names and sizes of variables

Single Stepping Pac-n-Zoom Macros    -    How to single step macros


Introduction

The Macro Menu provides functions to record and play back macros. Macros are instructions that mimic user activity with no actual user activity. Macros are a language add-on to Pac-n-Zoom. They allow the user to automatically run most of the features of Pac-n-Zoom. Their syntax is similar to other interpreted languages. Macro syntax includes variable definition, variable assignment, labels, gotos, loops, conditionals, and functions. The syntax has built-in features for reading a graphics file, IFR enhancement of the file, and writing the result back out to a graphics file.


Description

Macros can be automatically generated by using the "Record Macro" drop-down menu in Pac-n-Zoom. They can also be created using any text editor. The macro would be put in a text file with a *.pzm extension (e.g., DHWP_1_Seg.pzm). They can be started in two ways.

If the macro file is put in the current working directory (CWD - normally the directory that Pac-n-Zoom is in), you will see from GUI (Pull-Down Menu: Macro -> Run Macro). A list will come up that shows the Pac-n-Zoom macros in the CWD. When you select the macro and click "OK", it will run.

The macro can also be started by adding a MACRO section to the Pac-n-Zoom configuration file ("pacnzoom.cfg"); e.g. add the following three lines:


# MACRO
macro1
*

Macros use the file extension "pzm". Macros default to interactive mode. Macros can be executed in batch mode when the program starts by adding a BATCH flag to the top of the Pac-n-Zoom configuration file; i.e. add the following line:

~ Batch

 Macros run interactively use all of the Pac-n-Zoom display capability and, when they exit, they leave the user at that point in Pac-n-Zoom. Macros run in batch mode work with no display and, when they exit, the program exits.

How to Record Pac-n-Zoom Macro
Pac-n-Zoom allows macros to be written with a text editor or the GUI commands can be recorded with Pac-n-Zoom's macro record feature (Macro->Record in the GUI).

To use the macro recorder, you simply start the recording feature, execute the GUI commands, and end the recording feature [ Example ]. The recorded macro is saved in a text file in the user chosen directory.


Creating a Macro Using a Text Editor
A text editor is a type of program used for editing plain text files. Windows comes with Notepad, but you probably want something stronger to edit macros.

More on Creating macros

Macro Commands

The following macro commands can be used interactively or with batch mode (except where noted):

AddFile(%filename)  :
Add file to the golden library that will be used to create golden text.

AddFrame(%filename)  :
Add frame to a video file.

AddPage(%filename)  :
Add filename to the PNH/PNZ output file. This command is used to build multiple page documents.

Autoseg()  : Run auto-set segmenter.

Beep()  : Notify the user with an audible sound.

This command cannot be used in batch mode.

Break  : Break out of loop.

Call  functionname( %param1,...,%paramN)  :
Go to function and pass parameters within "()".

Clear()  : Clear the current image from the raster buffer.

Clearlib  : Clear golden library.

Continue  : Go to top of loop.

Copy()  : Copy the rectangular selected section of the image in the raster buffer to the window clip board.

Cut()  : Cut the rectangular selected section of the image in the raster buffer from the raster buffer to the window clip board.

Done()  : Terminate the current macro command.

Examples:
The following loop writes the library files A_ARL16.pzl, AB_ARL16.pzl, and timrom41.pzl. AB_ARL16.pzl references A_ARL16.pzl. Setting the WriteGoldenFileFlag, causes the *.pzl extension.
%AcceptableTolerance=0
%WriteGoldenFileFlag=1
Clearlib
%NextBCGoldenFileName="A_ARL16"

Open("bmp\abc\A_ARL16.bmp")
SaveAs("A_ARL16.pnh")
Done()

%AcceptableTolerance=0
%WriteGoldenFileFlag=1
AddFile("A_ARL16")
%NextBCGoldenFileName="AB_ARL16"

Open("bmp\abc\AB_ARL16.bmp")
SaveAs("AB_ARL16.pnh")
Done()

%AcceptableTolerance=0
%WriteGoldenFileFlag=1
Clearlib
%NextBCGoldenFileName="timrom41"

Open("bmp\abc\timrom41.bmp")
SaveAs("timrom41.pnh")
Done()
Stop()

ElIf  ( CONDITIONAL_STATEMENT )  :
Start of an "Else if" clause.

Else  : Start of an "Else" clause.

EndCmd()  : Stop macro and begin normal execution.

EndIf  : End of an "If" clause.

EndLoop  : End of all "While", "Loop", and "For" loops.

Enhance()  : Convert the image in the raster buffer to primitive vector.

FitHorz  : Set the size of the current graphics file to fit horizontally.

FitPage  : Set the size of the current graphics file to fit a full page.

For   %var  {  FILENAME_LIST  }  :
Loop once for each file within "{}". End with "EndLoop".

"For" loop syntax uses FILENAME_LIST as its incrementer (it loops once for each file within "{}"). The list includes quoted filename strings separated by commas. Wildcard expansion is supported.
e.g.
for %var in (%filename, "filename", "*.bmp")

Examples:
The following loop opens and displays all *.bmp files.
For %Var in { "*.bmp" }
Open %Var
EndLoop

To explicitly state the file order use the following macro statements.
For %Var in { "1.bmp", "2.bmp",
"3.bmp", "4.bmp", "5.bmp",
"6.bmp", "7.bmp", "8.bmp",
"9.bmp", "10.bmp", "11.bmp",
"12.bmp", "13.bmp", "14.bmp"}
Open %Var
EndLoop

The following macro takes a group of bitmap files (ie., first.bmp, add1.bmp, add2.bmp, add3.bmp, etc. to last.bmp) and creates a single file, "c:\files\first.pnz", that has multiple pages.
%CWD = "c:\files\"
%filein = %CWD + "first.bmp"
open(%filein)
%fileout = Pathname(%filein) + Filename(%filein) + ".pnz"
saveas(%fileout)
for %x in {"add*.bmp", "last.bmp"}
addpage(%x)
endloop
done
stop

Function   functionname  :
Start of function.

GoTo   label  : Go to a label.

GoToPage(%pagenum)  :
Go to a specific page in a multiple-page document.

If  ( CONDITIONAL_STATEMENT )  :
Start of an "If" clause.

KeyNext()  : Used within a loop to stop the program and wait for the PgDn key. PgDn falls out of the loop on the last value in the loop.

May also be used outside of a loop for interactive stop.

This command cannot be used in batch mode.

KeyNextPrev()  : Used within a loop to stop the program and wait for the PgUp or PgDn key (or Mouse Left/Right if MousePage is turned on).

PgDn falls out of the loop on the last value in the loop.

PgUp stops at the first value in the loop.

This command cannot be used in batch mode.

Label  : Label used for "GoTo"s.

Loop (n)  : Loop n times. End with "EndLoop".

The parenthesis around the indicated number of loops are optional. The optional syntax follows.

    Loop n

Maximize()  : Show the image in the raster buffer at the largest integral size which will fit on the display.

Message(%message)  :
Notify the user with the message.

This command cannot be used in batch mode.

MousePage()  : Used within a loop to PgDn/PgUp with Mouse Left/Right. Requires a stop on a KeyNextPrev.

This command cannot be used in batch mode.

Normal()  : Show the image in the raster buffer at 1:1 pixel size.

NormalPage()  : Turn off MousePage().

This command cannot be used in batch mode.

Open(%filename)  :
Open a graphics file, and loads the image into the raster buffer.

The parenthesis around the file name are optional. The optional syntax follows.

   Open  %filename

PageSize(%pagesize)  :
Set the size of the current graphics file. 100(%) is 1:1.

Paste()  : Paste from the window clip board to a rectangular selected section of the image in the raster buffer.

Pause(%seconds)  :
Delay the program for the given number of seconds. This command cannot be used in batch mode.

The parenthesis around the indicated number of seconds are optional. The optional syntax follows.

   Pause  %nn

Print  : Print the current graphics file to the printer.

Return  : Return from function.

Save()  : Save the image in raster buffer to a file using the current file name.

The file format used is determined by the current file name's extension.

SaveAs(%filename)  :
Save the image in raster buffer to a file using a new file name.

The file format used is determined by the current file name's extension.

The parenthesis around the file name are optional. The optional syntax follows.

   SaveAs  %filename

Segmentation  : Use Pac-n-Zoom segmentation on the current graphics file.

Selection( %ulx, %uly, %lrx, %lry)  :
Select a rectangular section of the image in the raster buffer.

%ulx: The horizontal location of the upper left corner of the selected rectangle.

%uly: The vertical location of the upper left corner of the selected rectangle.

%lrx: The horizontal location of the lower right corner of the selected rectangle.

%lry: The vertical location of the lower right corner of the selected rectangle.


Sleep(%seconds)  :
Delay the program for the given number of seconds. This command cannot be used in batch mode.

The parenthesis around the indicated number of seconds are optional. The optional syntax follows.

   Sleep  %nn

Stop()  : Stop macro and begin normal execution.

SvgColorSelect( %SrcFile, %ThRGB, %Flg_LT)  :
Select all the blobs from the source file whose colors are less than (or greater than if Flg_LT is 0) ThRGB. The qualifying blobs are returned in the output file which is an SVG file. All blobs are described by closed SVG paths.

%SrcFile: The file the blobs will be extracted from. The file must be a SVG file.

%ThRGB: The blobs will be compared to this color. %ThRGB is of the format 0xRRGGBB.

%Flg_LT: The flag that selects whether the qualifying blobs are less than (Flg_LT == 1) or greater than (Flg_LT == 0) than ThRGB.

%OutFile: A SVG output file is returned that contains all the qualifying blobs. The output file is named from the source file. The output file name (except for the extension) has "_sel" added to the file name. For example, if the source file is named source.svg, the ouput file will be named source_sel.svg.

Example:
SvgColorSelect(yf-6.svg, 0x445566, 1)

Which Returns: yf-6_sel.svg


SvgSelect( %SrcFile, %SelFile, %DelFlg)  :
Select all the blobs from the source file that intersect (or don't intersect when DelFlg == 1) the select blob. The qualifying blobs are returned in the output file which is an SVG file. All blobs are described by closed SVG paths.

%SrcFile: The file the blobs will be extracted from. The file must be a SVG file.

%SelFile: The file that contains the blob that will determine which blobs from the source file will be extracted. The file must be a SVG file.

%DelFlg: The flag that selects whether the intersecting blobs are included (DelFlg == 0) or deleted (DelFlg == 1) from the output file.

%OutFile: A SVG output file is returned that contains all the qualifying blobs. The output file is named from the source file. The output file name (except for the extension) has "_sel" added to the file name. For example, if the source file is named source.svg, the ouput file will be named source_sel.svg.

Example:
SvgSelect(yf-6.svg, yf_sel.svg, 1)

Which Returns: yf-6_sel.svg


ThresholdSeg  : Use threshold segmentation on the current graphics file.

While  ( CONDITIONAL_STATEMENT )  :
Start of a "While" loop. End with "EndLoop".

ZoomIn()  : Zoom into the rectangular selected section of the image in the raster buffer.

ZoomOut(%nn)  : Zoom out of the rectangular selected section of the image in the raster buffer by the indicated number of percent.

The parenthesis around the indicated number of percent are optional. The optional syntax follows.

   ZoomOut  %nn

ZoomTo  : Zoom into the rectangular region given by previous Selection().

Variables

Variables are automatically generated. The data type is determined by use. Variable names are case insensitive. They start with '%'. All other characters must be 'a-z', 'A-Z', '0-9', and '_'. Variables are allowed within strings: e.g. "X = %X" and %X = 59 would expand to "X = 59".

Supported Variable Types:
long e.g. %var = 1
boolean e.g. %var = TRUE
string e.g. %var = "string"
double e.g. %var = 123.456
variable e.g. %var = %var2

Rval Functions

Exist(%filename)  :
Returns boolean

Filename(%filename)  :
Returns string file name from %filename
e.g.
Pathname("c:\work\file.ext")
would process to "file"

Fileext(%filename)  :
Returns string file extension from %filename
e.g.
Pathname("c:\work\file.ext")
would process to ".ext"

Pathname(%filename)  :
Returns string file path from front of %filename
e.g.
Pathname("c:\work\file.ext")
would process to "c:\work\file"

Operators

++  : Increment variable
e.g.
%var++

--  : Decrement variable
e.g.
%var--

+  : Concatenate string variable
e.g.
%var = Pathname(%a) +
   Filename(%b) +
   Fileext(%c)


Reserved Variables

The following are reserved variable names used within macros. With the exception of the "read only" reserved variable names, the following are reserved variable names which are set from the configuration file or may be set with a macro assignment.

%AcceptableTolerance
%AggregatePixelSize
%AutoThresholdLevel
%CWD - Current working directory
%CollateNextPageFlag
%ColorNumberLimit
%ColorTransformation
%CurrentBCGoldenFileName
%Description
- Macro Description Text
%Destination
%DisplayTier1Blobs
%Dithering
%EliminateOrphanPixels
%EliminateTransitionalBlobs
%ErrorLog
%LimitColorNumber
%MergeCompatibleColors
%MergeNearColors
%MonitorPixelSizeHoriz
%MonitorPixelSizeVert
%MonitorPixelUnits
%NULL
- Read only
%NearColorLimit
%NextBCGoldenFileName
%OrphanMCDLimit
%OutputResolutionHoriz
%OutputResolutionVert
%OutputSizeHoriz
%OutputSizeUnits
%OutputSizeVert
%OutputTo
%PnzFileType
%PrinterPixelSizeHoriz
%PrinterPixelSizeVert
%PrinterPixelUnits
%RunTier1
%RunTier2
%Source
%SweepWeightRow
%ThresholdHighReal
%ThresholdLevel
%ThresholdLowReal
%Tier1CCLevel
%Tier2CCLevel
%WriteGoldenFileFlag
FALSE
- Read only
NULL - Read only
TRUE - Read only

CONDITIONAL_STATEMENT

The syntax of conditional statements is almost exactly like "C" language syntax.
Syntax Meaning
== equal
!= not equal
<= less than or equal
< less than
>= greater than or equal
> greater than
&& logical and
|| logical or
( left parenthesis
) right parenthesis
!%a OR !a not parameter (Bool)
exist(a) truth of file existing
!exist(a) truth of file not existing


Macro Programming Rules

A.  Macro file names are limited to 8 characters with a 256-character description. File name characters must be 'a-z', 'A-Z', '0-9', or '_'.

B.  Macro commands are case insensitive except when they appear within quotes.

C.  Macro commands are line oriented (271 characters maximum).

D.  Indentation is allowed, but use spaces (do NOT use tabs).

E.  Blank (empty) lines are treated as comments.

F.  Comments begin with a semi-colon ";" which can occur after a valid statement.

G.  String values must be double-quoted.

H.  A file must end with either an exit or a stop command.

I.  "!" in conditionals must not be followed by a space.
e.g.,
!%X or !exist(%X)

J.  A space is required between opcodes and parameters within a conditional set of parentheses (if, elif, and while commands), and a space is a good idea between all opcodes and parameters.

K.  Filenames should start with ".\" or "%CWD\" before the name except when in "for" loops because those parameters are understood to be filenames.


Home Table of Contents Main Diagram
© 2004 - 2011 Accelerated I/O, Inc, All rights reserved.