Oc-witm-user0 - Teledyne Dalsa

Transcript

Coreco Imaging • 7075 Place Robert-Joncas, Suite 142 • St-Laurent, Quebec, Canada • H4M 2Z2 http://www.imaging.com WiT User’s Manual Edition 8.0 Part number OC-WITM-USER0 *OC-WITM-USER0* NOTICE © 2003 Coreco Imaging Inc. All rights reserved. This document may not be reproduced nor transmitted in any form or by any means, either electronic or mechanical, without the express written permission of Coreco Imaging Inc. Every effort is made to ensure the information in this manual is accurate and reliable. Use of the products described herein is understood to be at the user’s risk. Coreco Imaging Inc. assumes no liability whatsoever for the use of the products detailed in this document and reserves the right to make changes in specifications at any time and without notice. Microsoft and MS-DOS are registered trademarks; Windows, Windows 95, Windows NT, and Windows XP are trademarks of Microsoft Corporation. All other trademarks or intellectual property mentioned herein belong to their respective owners. Printed on September 30, 2003 Document Number: OC-WITM-USER0 Printed in Canada Contents Introduction ....................................................................................................................................1 Igraphs.............................................................................................................................................3 Creating, Reading, and Saving Igraphs ........................................................................................4 Creating a New Igraph ............................................................................................................4 Saving an Igraph......................................................................................................................4 Reading an Existing Igraph .....................................................................................................5 Changing Igraph Design Size ..................................................................................................5 Customizing the Grid ...............................................................................................................6 Running Igraphs ...........................................................................................................................6 Starting an Igraph....................................................................................................................6 Stopping an Igraph...................................................................................................................7 Adjusting Run Speed ................................................................................................................8 Data Animation........................................................................................................................8 Changing Run Speed while an Igraph is Running ...................................................................9 Editing Parameters while an Igraph is Running......................................................................9 Pausing Igraph Execution........................................................................................................9 Resuming a Paused Igraph ......................................................................................................9 Single Step Execution...............................................................................................................9 Igraph Operators.........................................................................................................................10 Operator Appearance on Igraphs ..........................................................................................10 Moving Operators on an Igraph ............................................................................................10 Parameters as Inputs .............................................................................................................11 Operator Color Indicators .....................................................................................................12 Editing Operator Properties ..................................................................................................12 Links...........................................................................................................................................13 Creating Links........................................................................................................................13 Link Direction ........................................................................................................................13 Editing Links ..........................................................................................................................14 Editing Link Properties..........................................................................................................14 Frayed Link Ends...................................................................................................................14 Probes ....................................................................................................................................14 Link Junctions ............................................................................................................................15 Creating a Junction................................................................................................................15 Junction Snap Priority ...........................................................................................................15 Deleting a Junction ................................................................................................................16 Sync Junctions........................................................................................................................16 Annotation on Igraphs ................................................................................................................17 Manipulating Igraph Operators, Links, and Annotations ...........................................................17 i Selecting Igraph Objects ........................................................................................................17 Copying Igraph Objects .........................................................................................................18 Cutting Igraph Objects...........................................................................................................18 Pasting Igraph Objects ..........................................................................................................18 Duplicating Igraph Objects....................................................................................................19 Cut and Paste Across Igraphs................................................................................................19 Undoing the Last Igraph Edit Action .....................................................................................19 Pick Tolerance .......................................................................................................................19 Igraph Object Names ..................................................................................................................20 Subgraphs ...................................................................................................................................20 Making a New Subgraph ........................................................................................................21 Subgraph Ports ......................................................................................................................22 Displaying a Subgraph...........................................................................................................23 Editing a Subgraph ................................................................................................................23 Promoting Parameters ...........................................................................................................24 Changing a Subgraph Icon ....................................................................................................24 Sharing Subgraphs using WIC ...............................................................................................25 Creating a WIC File from an Igraph ..................................................................................25 Using a WIC File as a Subgraph........................................................................................25 Performance Tuning ...................................................................................................................26 Changing Parameters while Running ....................................................................................26 Debugging an Igraph .............................................................................................................26 Status Windows .................................................................................................................26 Run Speed..........................................................................................................................27 Operator Status Colors.......................................................................................................28 Data Object Animation ......................................................................................................28 Link Properties for Debugging ..........................................................................................29 Parallel Execution..................................................................................................................30 Explicit Parallelism............................................................................................................30 Pipelined Parallelism .........................................................................................................30 Using the Profiler...................................................................................................................31 Profiling with Multiple Threads.........................................................................................32 Adjusting the Number of Threads......................................................................................33 Advanced Igraph Concepts.........................................................................................................33 Igraph Design Techniques .....................................................................................................33 Placement of Operators and Links .....................................................................................34 Meaningful Icons and Names ............................................................................................35 Use of Blank Spaces ..........................................................................................................35 Minimize Link Crossovers.................................................................................................36 Sloped Links ......................................................................................................................36 Annotations........................................................................................................................36 Subgraphs ..........................................................................................................................36 Goto Operator ....................................................................................................................37 Connecting an Operator to Itself........................................................................................37 Common Control Constructs..................................................................................................38 If-Then-Else.......................................................................................................................38 For Loop ............................................................................................................................39 ii While Loop ........................................................................................................................39 Sequencer ..........................................................................................................................39 Collector ............................................................................................................................40 The Scheduler.........................................................................................................................41 Scheduling Strategy ...........................................................................................................41 Data Transport ...................................................................................................................41 Operators.......................................................................................................................................43 Invoking Operators.....................................................................................................................43 Getting Help for Operators.........................................................................................................44 Getting Help for an Operator Port ........................................................................................44 Operator Parameters ...................................................................................................................45 Parameter as Input.................................................................................................................47 Special Operators .......................................................................................................................47 display....................................................................................................................................47 Display Operator Properties ..............................................................................................48 Image Properties Panel ......................................................................................................51 Pixel Range Panel ..............................................................................................................54 Image Menu.......................................................................................................................54 General Object Menu.........................................................................................................55 graph......................................................................................................................................55 Graph Operator Properties.................................................................................................56 Graph Property Panel.........................................................................................................58 Displaying Exact Coordinates ...........................................................................................58 Curve Types.......................................................................................................................59 Input Types ........................................................................................................................59 Multiple Curves .................................................................................................................59 Selecting Curves ................................................................................................................59 Zoom and Pan....................................................................................................................59 Memory and Counter .............................................................................................................60 Processing Data Fields..........................................................................................................60 GetField and PutField ........................................................................................................60 Field Names.......................................................................................................................61 Field Names of Nested Objects .........................................................................................61 Specifying Fields for Multi-Dimensional Data..................................................................62 Processing Object Vectors .....................................................................................................63 Sequencer ..........................................................................................................................63 Partition and SortObj .........................................................................................................64 Calc and Cast .....................................................................................................................64 C Code Operator....................................................................................................................64 Operator Icons ............................................................................................................................64 Icon Cache .............................................................................................................................65 Multiple Implementations ..........................................................................................................65 Libraries .....................................................................................................................................66 Standard.................................................................................................................................66 Frame Grabber and Hardware..............................................................................................68 SmartSeries ............................................................................................................................68 iii Data Objects ..................................................................................................................................71 Viewing Objects .........................................................................................................................71 Viewing Objects in Graph Mode............................................................................................71 Viewing Objects in Script Mode.............................................................................................71 Viewing Object Files ..............................................................................................................71 Studying Images .........................................................................................................................72 Adjusting Image Colors..........................................................................................................72 Studying Pixel Values.............................................................................................................73 Plotting Pixel Profiles ............................................................................................................74 Group Control of Images .......................................................................................................74 Resizing Images..........................................................................................................................75 Setting an Exact Pixel Scale...................................................................................................75 Setting an Exact Image Frame Size........................................................................................76 Zooming and Panning Images................................................................................................76 Image Types ...............................................................................................................................77 Printing Data Objects .................................................................................................................77 Printing Images......................................................................................................................77 Printing a General Data Object.............................................................................................77 Object Window Placement .........................................................................................................78 Reading and Writing Object Files ..............................................................................................78 Frame Grabbers............................................................................................................................79 Setup...........................................................................................................................................79 Common Operators ....................................................................................................................79 Frame Grabber Tool ...................................................................................................................80 Emulator .....................................................................................................................................81 Usage Techniques..........................................................................................................................83 Graphic Objects ..........................................................................................................................83 Selecting Graphic Objects......................................................................................................83 Deselecting Graphic Objects .................................................................................................84 Moving Graphic Objects ........................................................................................................84 Deleting Graphic Objects.......................................................................................................84 Copying Graphic Objects.......................................................................................................85 Pasting Graphic Objects ........................................................................................................85 Undo the Last Edit Action ......................................................................................................85 Editing Graphic Objects.........................................................................................................85 Properties of Graphic Objects ...............................................................................................86 Annotation Objects.................................................................................................................86 Creating Annotation Objects..............................................................................................86 Annotation Object Properties.............................................................................................87 Pen Color of Annotation Objects.......................................................................................87 Fill Color of Annotation Objects .......................................................................................88 Changing Annotation Text.................................................................................................88 Annotation Object Fonts ....................................................................................................88 Selecting Windows .....................................................................................................................88 iv Resizing Windows......................................................................................................................89 Zooming and Scroll Bars............................................................................................................90 Zooming .................................................................................................................................90 Restoring to Original Scale and Position After Zooming ......................................................90 Scroll Bars .............................................................................................................................90 Printing .......................................................................................................................................91 Script Mode ...................................................................................................................................93 Script Cells .................................................................................................................................93 Displaying the Contents of a Script Cell ................................................................................93 Selecting Script Cells .............................................................................................................94 Deleting Script Cells ..............................................................................................................94 Renaming a Script Cell ..........................................................................................................94 Sequencer and Collector in Script Mode....................................................................................95 Script Files..................................................................................................................................95 Running a Script ....................................................................................................................95 Saving a Script .......................................................................................................................96 Reading a Script File .............................................................................................................96 Erasing the Current Script .....................................................................................................96 Editing a Script File...............................................................................................................96 Network .........................................................................................................................................99 WiTRAS - Remote Access Server .............................................................................................99 Installing TCP/IP .................................................................................................................100 eWiT.........................................................................................................................................100 eWiT on Start Up .................................................................................................................101 Assigning Subgraphs............................................................................................................102 Adding a Remote Connection...............................................................................................103 Removing a Connection .......................................................................................................104 Editing Settings of a Connection..........................................................................................104 Configuration ..............................................................................................................................105 Library and Server Configurations ...........................................................................................105 User Preference Options...........................................................................................................106 Command Line Options ...........................................................................................................108 Safe Mode ................................................................................................................................108 System Registry........................................................................................................................108 Color Configuration .................................................................................................................109 Workspace Object Color Types............................................................................................109 Directories ................................................................................................................................110 Read and Write Directories .................................................................................................110 International Language Support ...............................................................................................111 Choosing a Language ..........................................................................................................112 Supported Languages...........................................................................................................112 Creating Translations for Operators ...................................................................................112 Coreco Imaging Contact Information.......................................................................................115 v vi Introduction This manual describes the WiT program and its various features to help you design and run effective and efficient image processing and analysis algorithms without writing code. It is meant for users who have some basic understanding of WiT is and the kind of things it can do. If you have never used or seen WiT before, please read the Getting Started manual first. From this manual, you will learn how to create and execute igraphs, debug igraph algorithms, interface with frame grabbers, and execute algorithms in parallel on multiple CPUs and in a distributed network. WiT has an open architecture which allows user C/C++ code to be added to augment and improve the standard WiT operators. It also allows C/C++ programs to be written directly without involving igraphs at all. Those features are explained in the Programmer’s Manual. WiT uses two environment variables: WITHOME and WITUSR. They are referred to in this manual as $WITHOME and $WITUSR respectively. $WITHOME is the directory where WiT was installed. $WITUSR is the directory where your WiT related work is kept. Usually $WITHOME is the same as $WITUSR. However, when you do not have write access to $WITHOME (for example, a classroom situation in which WiT is installed with read only access on a file server), then $WITUSR can be set to point to a directory where you do have write access. 1 2 Igraphs An igraph is a graphical representation of an imaging algorithm. On an igraph, each icon represents an operation, such as reading an image file, performing a convolution, or generating a lookup table. Operators are represented by graphical icons. This makes your imaging algorithm pleasant to work with and easy to understand. The properties of each operator can be interactively modified. Properties are displayed below the icon so that the igraph is a complete representation of your algorithm. An operator takes a number of input data objects and produces output data objects. Data objects are saved in memory and can be shared by different operators through the use of links. A data object is automatically freed when no operator or display need it anymore. Flow control operators such as if-then-else and for-loop allow you to incorporate conditional logic within an igraph. When an operator executes, WiT dynamically shows you which data objects are produced, where the data is passed to, and which inputs have been processed. Controls for pausing, continuing, or single stepping igraph execution are available. Igraphs present a quick way of prototyping and testing image analysis procedures without committing hours of tedious programming. With meaningful graphical icons for operators and parameter values displayed directly below each operator, an igraph is not only the means of executing an algorithm, it also serves as concise and accurate documentation for it. Links can branch off into an unlimited number of directions. This allows an operator to pass its outputs to multiple operators which can then be executed in parallel, provided that you have more than one processing resource available. Portions of an igraph can be encapsulated into a subgraph for good top-down design. There is no limit to the number of nesting levels of subgraphs. In addition to graph mode, WiT also provides a different execution mode: script mode, used for quick testing of ideas. Details can be found in Script Mode. To run WiT in graph mode, do one of the following: • • • Use the command line option -mode graph. Click the tool bar button. Bring up the Options panel. Choose Graph for Mode. 3 Creating, Reading, and Saving Igraphs Creating a New Igraph To create a new igraph, do either one of the following: • • Click the tool bar button. Select menu item File/New. The WiT workspace is cleared and any pop-up frames generated by the previous igraph execution are taken down. Pop-up frames can be optionally retained. Saving an Igraph To save an igraph, do one of the following: • • Click the tool bar button. Select menu item File/Save. To save an igraph to a different file name, select menu item File/Save as.... When you save an existing igraph to itself, WiT will do it quietly. If the igraph is new, selecting File/Save has the same effect as selecting File/Save as.... When saving an igraph to a different name, a file dialog comes up for you to select a file name. WiT adds the ‘igr’ extension automatically to the name you enter, so you do not have to type that yourself. If you try to save an igraph as another file name and that file already exists, WiT will ask for your confirmation to overwrite the previous file. WiT keeps a maximum of 10 backup files when an igraph is saved. If for any reason you want to revert to an older version of an igraph, checking the file dates of the backup files, which has the format name.bak.0, name.bak.1, etc. Rename the one you want with a .igr extension. Then you can load it into WiT. 4 An igraph is stored with most of the editing options that are used at the time the igraph is saved. These are: • • • • • • Design size Workspace window size Subgraph level Grid size Grid visibility Pick tolerance With this information, WiT can restore the (possibly different) working environments that you used to create different igraphs. For example, you probably want to use a dense but invisible grid to design a very complex igraph with many small objects, but a large and visible grid for simple igraphs. Reading an Existing Igraph To read a previously created igraph, do one of the following: • • Click the tool bar button. Select menu item File/Open. A file dialog comes up for you to select an igraph file. Igraphs have a ‘igr’ extension. The initial directory is the current working directory. After an igraph is loaded, the current directory is set to where the igraph is loaded from. Changing Igraph Design Size Igraphs have a design width and height. When the workspace window is smaller than the design size, scroll bars will appear automatically. If you want to change the design size, select the Windows/Design Size menu item. Then either type in the desired width and height in pixels, or click the button to set the design size to be the current window size (the scroll bars will then disappear). Changing Igraph Design Size 5 Customizing the Grid The grid that is shown on the workspace is not only used for decoration. When snap is enabled (from the Options Panel), objects will snap to a grid point when placed or moved on the workspace. When making a link, however, operator ports and link corners have priority over the grid. For example, if you branch off from a link in the middle of one of its link segments, then WiT will choose to break the segment at a grid point. But if you branch off from near a link corner, WiT will break the segment right at the corner. This usually results in a better looking igraph. If you want to position objects at a different resolution, you can change the grid size. If you set the grid size to 0, the grid will not be displayed. Sometimes you may find the grid distracting, in which case you can hide the grid. The effects of snapping are still enabled even when the grid is hidden. Running Igraphs Starting an Igraph To start running an igraph, do one of the following: • • • (turtle, boy, rabbit, and flash) buttons. These buttons all start Click any one of the the igraph running, with different speeds. Select Run/Start. Press the F5 function key. You can also change the run speed from the Options Panel. Before an igraph starts, all pop-up windows from the previous execution are cleared automatically. Pop-up frames can be optionally retained. 6 The execution is performed differently depending on the run speed: • • • • The status indicator cycles between and . Operators turn green when they execute, and their names are reported on the status window. A one second pause is added after each operator before proceeding to the next. Token travel on links is animated slowly so that it is easy to follow the progress of the igraph. The status indicator cycles between and . Operators turn green when they execute, but the pause after each operator is shorter, and token travel is animated faster than . The status indicator cycles between and . Operators turn green when they execute, but there is no pause added after execution. Token travel animation is turned off. All feedback is disabled. Even the status indicator becomes a static , thus allowing the igraph to run absolutely unimpeded. You cannot modify an igraph during execution, but you can modify operator and link parameters. In addition to turning green to indicate execution, other colors are used to indicate different operator states. Stopping an Igraph To stop an executing or paused igraph, do one of the following: • • Click the button. Select the Run/Stop menu item. WiT may take a while to respond to your stop request, because it has to wait till all currently active operators have finished before it can stop. The status indicator changes to as soon as the stop request is received by WiT. When all the active operators are finished, the status indicator then changes to to indicate that the igraph is stopped and is ready for editing. You can stop a running or paused igraph. Igraph execution cannot be resumed once it is stopped. 7 Adjusting Run Speed With the exception of speed, a delay is added to each icon or link as they are executed. These delays can be adjusted to your own preference. To do that, click the button next to the Speed control in the Options Panel. The Speed panel appears: Speed Panel The numbers shown next to each run speed is the unit delay in approximate milliseconds. The unit delay is applied to each operator when it executes, and to animated token travels when running in speed. or Data Animation If the run speed is or , data objects on igraphs is animated with red dots. A dot is produced whenever an operator has successfully produced a data object. The dot travels along links to an input port of another operator. This indicates which input of which operator the data object is being passed to. The operator icon then turns green to indicate that it is processing the data. Once an operator has finished processing, the dots at the input ports are erased. Therefore, at any time, the location of the red dots indicate accurately which stage your algorithm is executing at. When igraph execution is complete, all data objects which have not been processed will be displayed regardless of run speed. Data objects may remain at operator input or output ports, or at link junctions. 8 Changing Run Speed while an Igraph is Running You can dynamically change the run speed of an igraph while it is running by clicking any of the buttons, or changing the Speed setting from the Options Panel. Editing Parameters while an Igraph is Running While an igraph is running, you can edit operator or link parameters by bringing up the property panel, but you cannot modify the structure of the igraph, such as adding or deleting operators or links. You can apply new parameter values by pressing the button. This will close the properties panel. The button can be used to apply new parameter values to the igraph without closing the properties panel. Pausing Igraph Execution To pause an executing igraph, do one of the following: • • Click the button. Select the Run/Pause menu item. WiT may take a while to respond to your pause request, because it has to wait till all currently active operators have finished before it can pause. When the pause request is received by WiT, the status indicator changes to . When all the active operators are finished, the status indicator changes to to indicate that the igraph is now paused. When an igraph is paused, you are still not allowed to edit the structure of the igraph (such as adding or deleting operators and links). But you can study at leisure images and other objects which have popped up. Resuming a Paused Igraph To resume a paused igraph, simply run the igraph again. The igraph resumes where it was last paused. Single Step Execution When an igraph is idle (status indicator is ) or paused (status indicator is ), you can single step the next operator by using the (step into) or (step over) tool bar buttons, or choosing the Step into or Step over from the Run menu bar. The first time you press or , the first operator that will be executed is highlighted in green. But the operator is not executed yet. Then when you single step again, the highlighted operator is executed, and the next operator that will be executed is highlighted. 9 Pressing a with a subgraph icon causes all runnable operators within that subgraph to be executed before control is returned to you. If you press with a subgraph icon, then only the first executable operator within the subgraph is executed. Subsequent requests may schedule any other operator, which may or may not be part of this subgraph. Doing a with an operator has the same effect as a . Igraph Operators Operator Appearance on Igraphs Usually, an operator is shown on an igraph as an icon with the operator name at the top, parameters at the bottom, input ports on the left, and output ports on the right. Unconnected ports are denoted with solid black arrows. When connected, a port has a link attached to the location where the arrow used to be. The following figure shows a typical operator with some ports connected and some unconnected. An igraph operator is an igraph object, which in turn is a graphic object. Typical Operator Appearance Moving Operators on an Igraph An operator icon is a graphic object. The techniques discussed in Section graphic object. apply. In addition, there are techniques specific to operators which do not apply to graphic objects in general. These are explained below. You can drag individual operator icons without first selecting them. Normally, when you drag one or more operators, all the links connected to the operators stretch with the movement of the operators. This allows you to move operators without having to reconnect all its ports. If you do not want the links to stretch with the operators, hold the SHIFT key while dragging. Whether moving single or multiple icons, link connections are automatically made if an operator port happens to fall on a disconnected link end (shown as a frayed end . 10 If an operator is dropped on a link, and the input and output ports of the operator are of the same type and they line up, then the connection is automatically made also. Parameters as Inputs Sometimes it is necessary to make an operator parameter an input. For example, you may want to set the filter width of a low pass filter dynamically depending on the contents of the image itself. So you would like the filter width to be an input rather than a fixed value. Such an input can then be connected to a link to get its data. To convert a parameter into an input, select Input for the parameter: A panel then comes up to let you select the position of the parameter input port. Parameter input ports are always positioned on the bottom of the operator icon, so you only need to specify where along the bottom edge of the operator you want the port placed. Parameter input port positions are stored individually for each instance of an operator and the position is saved with the igraph. So the next time you load the igraph, parameter input ports will be correctly positioned. If a parameter on a fire-on-any operator is made into an input port, then the operator will fire whenever any one of the inputs, including the parameter inputs, arrives. All subgraph operators are of type fireon-any. 11 Operator Color Indicators Colors are used to indicate various operator states. These colors are user configurable. Color Meaning Red Selected Green Running Blue Output blocked Brown Waiting for user input Editing Operator Properties To edit the properties of an existing operator, click the right mouse button at the icon. The property panel for that operator is displayed. Set properties as desired, then hit the button. If you hit the button, all changes you made on the properties are discarded. 12 Links Igraph links represent the paths data takes when an igraph is executed. Links are always unidirectional, the direction of data-flow indicated by an arrow on the link. A link is an igraph object, which in turn is a graphic object. Creating Links To create a straight link between two operator ports: 1. 2. Point the mouse at the first operator port. While the mouse is there, click the left mouse button or hit the period (‘.’) key on the keyboard. A rubber band link should now be following your mouse. Move your mouse to point at the other operator port. While the mouse is there, click the left mouse button or hit the period (‘.’) key on the keyboard. To create a link with corners between two operator ports: 1. 2. 3. 4. 5. Start the link as before. Move mouse to position of first desired corner, then click the left mouse button. A corner is created. The link now rubber bands between the mouse and the corner. Repeat for additional corners. If a corner is mistakenly placed, hold down the CTRL key on the keyboard and click the left mouse button or hit the Delete keyboard key to backtrack (undo) one corner. If you are already at the beginning of the link, the link creating session will be terminated. If you back up all the back to the port, the link creation session is canceled. You can also abort the link creation session at any time by hitting the ESC key on the keyboard. Terminate the link by attaching it to another operator port as before. Once the link is attached at both ends, WiT will attempt to make the link look pretty by snapping all link segments to align with a port, junction, or the grid. This can be overridden later. You can only connect an input port to an output, or vice versa, but not two ports of the same type. You can connect a link to the middle of another link, or to a frayed link end . Since clicking deselects all previously selected objects, the period (‘.’) key method of starting a link is particularly useful when you want to create a link without losing your current selection (useful in tracing, for example). Link Direction The direction of a link is often implicitly determined by the kind of ports it is connected to: from an output to an input port. If you attempt to connect a link between two input ports, or between two output ports, WiT will warn you and refuse to make the link. When the direction of a newly created link 13 cannot be determined (e.g. a branch between two links), the data is assumed to flow in the direction that the link is created, i.e. following the order in which the points on the link are entered. Editing Links Once a link has been created, it can be edited: cut, paste, move, etc. A link is an igraph object. The general techniques for manipulating igraph objects apply. When you adjust links, WiT no longer tries to make the wire pretty by forcing it to lie along grid lines or multiples of 90 degrees. Editing Link Properties You can edit the properties of a link by clicking the right mouse button at it, which brings up the property panel. Unlike operators, all links have a common set of properties, but the property values may be different. Frayed Link Ends It is possible for a link to become disconnected from everything (for example, when you delete a node which has some connected links). Such dangling link ends are displayed with a frayed end on the igraph. You can connect a link to a frayed end by double clicking the left mouse button at the frayed end to start wiring, or you can connect an operator port to it by simply dropping an operator icon on top of the link end, provided the direct ion of the operator port is compatible with the direction of the link. Probes A probe on a link is a convenient mechanism to inspect data when an igraph is running. A probe behaves in exactly the same way as the display operator, but is more convenient and compact. When data flows along a link which has a probe, a pop-up window is created to display the data. The title of the window is the name of the link. 14 Link Junctions A link can have any number of branches coming from it, or any number of branches going to it, or both. The junction where links join or split from is shown with a solid black dot on an igraph. The following figure shows some examples of link junctions: Example Use of Link Junctions Outgoing links from a junction are used to make multiple instances of a token. Incoming links to a junction can be used for synchronization, or to simply feed different tokens to the same destination. When a token arrives at a junction which has multiple outgoing branches, the junction will hold the token if any of the ports that the branches are leading to is not ready to receive a token. During this time the junction will not accept any new tokens. Once all ports have received the token stored in the junction, the junction removes that token from its storage and is again ready to accept new tokens. Creating a Junction To create a junction and a link branch, point at the location on a link where you want the branch to come off, and double click the left mouse button (or use ‘.’). Make sure no operator ports are within the pick region, otherwise WiT will think you want to connect to the port. If the split is successful, a rubber band wire is created between the mouse pointer and a newly created junction on the link, shown as a large dot. You can have as many branches from a link as you want. This is how multiple instances of an object can be sent to different operators. Junction Snap Priority When a link is split, WiT uses the following rules, in order of preference, to put the junction at a visually pleasing position: 1. 2. 3. Existing link junctions. Existing link corners. Grid intersection point. 15 Deleting a Junction Junctions are not deleted directly. They are deleted when all branches from a link have been deleted. When a link is deleted from a junction, WiT employs some intelligence to determine whether the junction can be deleted or not. If a junction has only two links connected to it after a link is deleted, and one link is pointing towards the junction and the other one is pointing away from it, then the junction can be deleted, otherwise it is retained. It is therefore possible for a junction to have only links bringing data to it but no links carrying them away, or vice versa. Such a construct of course is not useful, but is a valid state during the igraph design process. Sync Junctions There are two kinds of junctions. The default type (shown with a solid black dot) simply passes data tokens from any input link to all of the output links of the junction. The second kind, called a sync junction, is indicated with a hollow circle. Sync junctions wait for one token to come from each of its input links, then fire a sync token (regardless of the data types of its input tokens) to all of its output links. If any of the links connected to the junction has been disabled, then the junction will not wait for a sync token to come from the disabled link. In other words, disabled links behave as if they have been deleted as far as sync junction behavior is concerned. Sync tokens do not carry any data. They are only used for synchronization purposes. This is useful, for example, if you need to initialize external hardware before it can be used. The initialization can be represented as WiT operators. You can send all the outputs of the initialization operators to a single sync junction, that way the image processing will start only after all the initialization operators are finished. Sync Junction To create a sync junction, first create a normal junction. Then click the right mouse button at the junction to bring up its property panel, and select Sync for its Type. Creating a Sync Junction 16 Annotation on Igraphs Often it is helpful to add annotations: text or simple graphics such as lines or circles, to document an igraph. Annotations are created and edited with the Graphics Editor. To bring up the Graphics Editor for annotating igraphs, select the Annotate... menu item from the Graph menu on the menu bar. Example Use of Igraph Annotation Some interactive operators, such as getData and iMeas, also use the Graphics Editor. During igraph execution, the focus of the Graphics Editor may switch automatically to any such operators as they execute. When igraph execution is complete and all interactive operators which use the Graphics Editor have terminated, the Graphics Editor will automatically change focus back to the igraph workspace. Manipulating Igraph Operators, Links, and Annotations There are three kinds of igraph objects: operator icons, links, and annotations. They are edited (select, move, copy, etc.) in a consistent manner. Selecting Igraph Objects An igraph object is a graphic object. The techniques discussed in Section Graphic Objects apply. An object turns red when it is selected. You can select multiple icons, graphic objects, and links. You can select all objects in an igraph with the menu item Edit/Select all. 17 The accuracy (how close you need to be) that you have to be when selecting objects can be adjusted from the Options panel. Copying Igraph Objects To copy selected objects to the buffer, do one of the following: • • • • Choose menu item Edit/Copy from the menu bar. Choose menu item Copy from the workspace menu. Click tool bar button. Type CTRL-C. Copied objects can be pasted later, possibly to a different igraph, or from a sub-graph to the top-level igraph. Links can be pasted to a sub-graph. Operators cannot be pasted to a sub-graph. Any object in a sub-graph can be copied. Cutting Igraph Objects If you want to cut one or more igraph objects, you need to select them first. Then do one of the following: • • • • • Choose menu item Edit/Cut from the menu bar. Choose menu item Cut from the workspace menu. Click tool bar button. Hit the backspace or DEL key. Type CTRL-X. Cut objects are saved in a buffer. They can be pasted later, possibly to a different igraph. Objects which have been previously added to a sub-graph can be cut, but objects which are originally in a subgraph cannot be deleted. Links can be pasted to a sub-graph. Operators cannot be pasted to a sub-graph. Pasting Igraph Objects To paste objects in the buffer to an igraph, do one of the following: • • • • 18 Choose menu item Edit/Paste from the menu bar. Choose menu item Paste from the workspace menu. Click tool bar button. Type CTRL-V. When you paste, WiT automatically goes into drag mode so that the objects can be placed interactively. Objects can be pasted from one igraph to another, or from a sub-graph to the top-level igraph. Links can be pasted to a sub-graph. Operators cannot be pasted to a sub-graph. Duplicating Igraph Objects Duplicating is the same as copying followed by pasting. It simply saves you some steps. There are two ways to duplicate currently selected igraph objects: • • Choose menu item Edit/Duplicate from the menu bar. Choose menu item Duplicate from the workspace menu. Cut and Paste Across Igraphs Sometimes you may want to incorporate in part or in full one igraph into another. This is easily done because the copy buffer (filled when you copy something using the Copy item from the workspace pop-up menu) is preserved when you load a new igraph. So all you need to do is load the igraph that you want to copy from, select the operators and links you want, and copy them. Then load the igraph you want to copy the objects to (or clear the workspace for a new igraph), and paste the objects. Undoing the Last Igraph Edit Action To undo the last igraph edit action, such as cut, copy, move, or paste, do one of the following: • • • • Choose menu item Edit/Undo from the menu bar. Choose menu item Undo from the workspace menu. Click tool bar button. Type CTRL-Z. Pick Tolerance When you need to select something on an igraph, the size of the square cursor tells you how accurate you need to be. You can change the pick tolerance from the Options panel. When you change the pick tolerance, the size of the square cursor will change accordingly. When objects are close together, you might want to lower the pick tolerance to allow finer, pin-point control. Conversely, you may set a coarse pick tolerance on sparse igraphs so that it is easier to pick things. The pick tolerance is not related to the snap or grid size. 19 Igraph Object Names Every node and link on an igraph must have a name. By default, the first instance of an operator is given the operator name. Any more occurrences of the same operator will have a number appended to the base operator name. You can rename an operator to whatever name you want, provided that same name is not already in use. If it is, then a number will be appended to the name to make it unique. If you delete the name altogether, WiT automatically replaces it with the default base name: a single underscore character (‘_’). Most printable characters can be used in instance names, including space (‘ ’), but you must avoid the backslash (‘\\’, used internally for hierarchical information) and the number (‘#’, used for instance numbers) characters. Also, WiT does not display any name that starts with the underscore character (‘_’). This is the mechanism used by WiT to selectively hide names of igraph objects. So do not use it as the first character of a name if you want that name displayed. Link names are assigned following the same rules. The only exception is that by default, link names are not displayed (they start with an underscore). By default, instance numbers are shown. However, when dealing with large igraphs, instance numbers can make the igraph look cluttered and are best turned off. In addition to specifying individual instance names, you can control how instance names are generally displayed using the Show names control item on the Advanced Options panel. They can be turned off completely (None), with only the base name showing (Base), or with the instance number showing as well (Instance). Subgraphs WiT allows you to encapsulate portions of an igraph into a subgraph, which is represented by a single icon with a red dot on its upper right corner, like this: The subgraph contains input and output ports which corresponds to the input and output ports on the subgraph icon. For example, the subgraph that is encapsulated by the above icon may be a graph like: You can use subgraphs to group a series of operations that you often use, or to make a large igraph easier to handle and understand. 20 A subgraph can in turn contain other subgraphs. There is no limit to the number of levels on an igraph. There is also no limit to the number of input or output ports on a subgraph, or the number of promoted parameters. Making a New Subgraph To create a subgraph, select the Graph/Add subgraph... menu item: The New Subgraph panel comes up: You can choose between a subgraph that is embedded in the same file as the main igraph (Graph), or a subgraph that has been previously saved as a WiT Code file (WiT code). An embedded subgraph is more convenient if the subgraph will only be used in one main igraph, whereas a sub-WIC is preferable if you plan to reuse a subgraph in many igraphs or if you plan to share the subgraph with other people. One aspect of sub-WIC files is that unless there is a corresponding igraph in the igraph search path, the contents of the sub-WIC cannot be viewed. This is sometimes useful when you want others to share what your subgraph can do, but not how you do it. If you select WIC you will need to specify the name of the WIC file. You will also need to specify whether the name of the WIC file should saved as an absolute path name, or whether WiT should use the igraph search path to locate it. An absolute path name is preferable if you know the exact location of the WIC is not going to change, and you don't want to manipulate the igraph search path. Using the igraph search path is better if it is possible that the WIC file may be moved around, such as when you redistribute your igraph designs. After editing the properties, click the button. A new operator appears in paste mode. After the operator is placed on the igraph, the new subgraph icon is displayed with a red dot at the upper right corner to indicate that it is a subgraph icon, with no input or output ports, like this: 21 If the subgraph is embedded, you will see a standard 61x41 icon with no ports. If you have chosen to use a sub-WIC, and the WIC file is available, the icon will appear with the size and number of ports when it was designed and saved. For embedded subgraphs, once a subgraph icon is created, you can copy and paste it in the same or other igraphs. But you cannot use a subgraph icon within its own igraph. That will cause an infinite recursive and WiT will not permit such attempts. Subgraph Ports Each port (both input and output) on a subgraph icon has a corresponding port operator in subgraph. Port operators look like ordinary operator ports, but are hollow and a bit larger. Data association between a port on the subgraph icon and the port operator inside the subgraph is established through port names. The position of the port operators is not relevant. For example, the black input and output ports in the following subgraph icon corresponds to the port operators in and out in the following subgraph: Subgraph input and output ports are operators found in the Control library. The number of input and output ports on a subgraph icon is automatically updated when you change the number of input and output operators inside the subgraph. The initial location of the ports on the subgraph icon is determined by their relative vertical positions in the subgraph. Input ports will be placed on the left, output ports on the right. If two ports of the same type are at the same vertical position, then the one on the left (smaller horizontal coordinate) will be assigned first. The positions of the ports can be adjusted using the icon editor, but you cannot change the number of input and output ports for a subgraph icon with the icon editor. The only way to change that is to modify the number of input and output operators in the subgraph. 22 Displaying a Subgraph To display a subgraph in a separate window, bring up the properties panel of the subgraph icon and press the button. Displaying a Subgraph Run time animation such as icon flashing and data object travels are shown on a displayed subgraph just like the main igraph. You can modify operator and link parameters on a displayed subgraph, to study the effects of different parameter values during run time, and to place or delete probes on links. But such changes are allowed for debugging purposes only. They will not be saved in the igraph file. Editing a Subgraph To edit a subgraph, click the button on the subgraph icon properties panel. 23 This will load the subgraph in the main workspace. While editing a subgraph, you can use copy and paste just like when you are editing a top level graph, including pasting objects from other igraphs. You can also save the current igraph while you are editing a subgraph. When you do that, the subgraph level is stored in the igraph file so that when you load the igraph next time, WiT automatically puts you back at the subgraph you were editing when you saved the igraph. This is useful when switching between igraph files for copying and pasting. When you have finished editing the subgraph, click the select the Graph/Up 1 graph level menu item. toolbar button to go up one level, or you can Promoting Parameters You can promote a parameter of any node or link in a subgraph to the subgraph icon. There is no limit to the total number of parameters promoted. To promote a parameter, click the button on the property panel (operator or link). A panel comes up for you to enter the names of the promoted parameters to be used on the subgraph icon. If you leave the name field blank for a parameter, then that parameter is not promoted. If that parameter was previously promoted, it will be unpromoted. Promoted parameters are shown in reverse print on an igraph. An Example of a Promoted Parameter Changing a Subgraph Icon You can change the port positions, icon size, and origin of an embedded subgraph icon with the Icon Editor just like an operator icon. The only difference is that you cannot add graphics to a subgraph icon. Bring up the operator properties panel and click the button to start the Icon Editor. If you are creating a new WIC file to be used as a sub-WIC, you can change the port positions, icon size, and origin using the Icon Editor also. But instead of clicking the button, go to the top level of your igraph, and choose Graph/Edit graph icon from the menu bar. Changing a subgraph icon does not affect the underlying subgraph in any way. 24 Sharing Subgraphs using WIC The subgraph we have created and manipulated was saved as part of the main igraph, or embedded. This means that no other igraph have access to that subgraph. The only way to share that is to copy and paste the subgraph. However, this has several drawbacks: • • • If the subgraph is modified and you want the new version to be used by all affected igraphs, you have to manually copy and paste the subgraph again. If you want to create a library of useful subgraphs and sell or give them to your customers, you may not want them to see what the actual underlying algorithm is. You need a way to allow your user to run your subgraphs without being able to read them. Each main igraph has to store a complete copy of the subgraph, which is a waste (albeit small) of disk space. Despite these drawbacks, embedded subgraphs are much easier to create. Also, since all the algorithm is captured in a single main igraph file, igraphs with embedded subgraphs are easier to maintain and to send to others, such as co-workers or other users. Creating a WIC File from an Igraph Load the igraph that you want to create the WIC from as the top level igraph. Then select Graph/Make WiT code from the menu bar. A WIC file with the same base name as the igraph will be created in the same directory. To check whether the WIC was made, click to pop-up the Graph menu again. You will see a check mark next to the Make WiT code item. This indicates that there is a corresponding WIC file for this igraph. When making an igraph into a WIC, the name of the igraph must be a valid operator name, since the WIC must behave like a regular operator. See Naming Conventions in the appendix for details. Using a WIC File as a Subgraph To use a WIC in an igraph, select Graph/Add subgraph... from the menu bar. The New Subgraph panel comes up (the same as for creating a new subgraph): 25 Select WiT code (WIC) for the Type. Then enter the name of the WIC file in the WIC file field. You can choose between Absolute and Use igraph search path. If Absolute is selected, the WIC file name is used exactly as typed. If the file is not found, WiT will report an error. If Use igraph search path is selected, the igraph search path is used to locate the file. For example, if the WIC name is myWic, and the igraph search path is .;$(withome)\allWics;c:\otherStuff Then WiT will look for the WIC in this order: .\myWic.wic $(withome)allWics\myWic.wic c:\otherSutff\myWic.wic Performance Tuning Changing Parameters while Running You can tweak the parameters of any operator while an igraph is running. Simply bring up the or button. The properties panel of the operator, make the changes, and click either the button applies the changes but keeps the properties panel open. The button applies the changes and closes the properties panel. This feature is particularly useful when the igraph is running in a continuous loop. Debugging an Igraph Status Windows The amount of information output to the WiT Status Window while an igraph is running can be controlled with the run speed. If the run speed is or , the name of each operator is displayed in the status window as it is executed, together with the server that the operator is scheduled to run on. If the run speed is or , this information is not displayed on the status window. 26 When an error occurs during igraph execution, an error message is printed on the status window, regardless of the run speed. If an igraph stops prematurely due to an execution error of an operator, the name of the offending operator is displayed in the status window. Run Speed When you are developing and experimenting with a new algorithm, choose either or speed. The igraph will run slowly and a lot of feedback is provided by WiT so that you can carefully study progress of the igraph and debug any potential problems. When the igraph is fully operational and you want minimum execution overhead, choose or speed to minimize execution time. 27 Operator Status Colors Operators which are still blue (waiting to send outputs) when an igraph stops prematurely are often good indicators of where the problem lies. Blue Operators often Indicate Dataflow Errors If an igraph stops because an operator encounters an error, in addition to reporting the offending operator in the status window, WiT selects the operator automatically and it will turn red. If the offending operator is within a subgraph, then the subgraph icon is also shown in red. Operators that Failed are shown in Red Data Object Animation With or speed, you can visually see data objects being produced, travel along links, and eventually being consumed. This allows you to not only understand the execution order of operators, but also the order with which data objects are produced and transported. If an igraph stops execution prematurely, you can study the location of the data objects to deduce the cause of the problem. For example, suppose we want to overlay a small image (say a company logo) onto a list of images. The dir and sequencer operator are to superimpose the same image (the output of readObj) to all images in the object directory whose name starts with the letters ‘sa’. Afterwards, we want to display the results. We used the file names as inputs to display so that the results will be shown in different windows. The igraph is shown below (demo\methods\design\deadlock). Example of Deadlock in an Igraph 28 This igraph will stop (deadlocked) after the first image is processed. With animation turned on, you can see from the locations of the objects that the graph stopped because the matchSize operator is waiting for an object at its lower input port. Backtracking from the inputs of matchSize, you can see that the top input of matchSize can be fed as many objects as there are image files in the object directory which starts with the letters ‘sa’, but only one object is sent to the lower port by the readObj #1 operator. The solution is to store the logo data object using a memStore operator which is then recalled every time an image is read by readObj #1. Now the graph can run to completion. The correct igraph is shown below (igraph deadlockFixed in demo directory). Deadlock Fixed Link Properties for Debugging Links provide a variety of properties to aid igraph debugging. Each link is individually controllable through its property panel. The most commonly used debugging aid a link provides is the ability to display data objects which pass along the link. Enabling the break point property of a link causes the igraph to pause whenever an object travels on the link. You can then single step or continue execution. If you have a large igraph and you know there is a problem within a particular section, you can change the Speed property on a link leading to that section to automatically change execution speed whenever an object travels on that link. This way you can slow down execution only at the problem area and resume at a faster speed once the area is passed. Link Properties for Debugging 29 Parallel Execution Explicit Parallelism Igraphs are ideal for describing parallel algorithms. For example, the following igraph indicates that the five different low-pass filters can be run after rdObj has produced its output. Parallel Igraph If you have a dual or quad Pentium PC, or if you have started external servers on a local area network, or if you have processor equipped boards, then WiT can automatically utilize all the processors available to execute as many of the filter operators as possible. For example, if you have a dual Pentium PC, then two of the filters can be run at any one time, thus cutting down overall execution time of this igraph to 60% of the time required if only one processor is available. Pipelined Parallelism In addition to simultaneous execution of parallel branches, WiT can also exploit pipelines. For example, in the igraph shown below images are continually acquired and sent through a processing pipeline. As soon as the first image has been acquired, it can be processed by the conv2d operator. The loop back link causes the acquire operator to acquire the next image. Therefore acquire and conv2d can be running at the same time. When the second image is available, acquire can grab the third image, conv2d can work on the second image, and getBlobs can process the first image. So three processors can now run in parallel. Depending on the number of processors available and the length of the pipeline, execution speed can be greatly improved through the use of pipelined execution. 30 Pipelined Igraph If you want to have more feedback about how WiT is scheduling operators on different processes or threads, use the Profiler. Using the Profiler WiT has a profiler which provides timing statistics useful for optimizing the execution speed of an igraph. As an example, load the igraph: ${WITHOME}\demo\Methods\Inspection\Check Gear Generate profile information by clicking the button on the WiT Studio tool bar. The igraph is run in flash mode and profile information is collected as the igraph executes. When the igraph stops, the Profiler window comes up: Profiler Window In the default view, the profiler shows the execution statistics of all operators in the main and subgraphs. The meaning of the columns can be found in section Profiler Window. You can learn a lot from studying the profile data. For example, we can see that apart from overlayData, which is a graphical interface operator, most of the computation time is used by getBlobs and getXEdges, contributing 24.9 and 9.5% to the total execution time respectively. So if you want to speed up the igraph by recoding some operators, you should consider these first. If you select the View/Advanced... menu item, the Profiler Metrics panel comes up. This panel gives you global information such as the degree of parallelism achieved, the maximum number of data 31 objects that existed at the same time during execution of the igraph, the maximum amount of cache memory used. Profiling with Multiple Threads The Profiler is very useful for studying how your igraph can take advantage of multiple processors. Even if you do not have a multiple-CPU computer, you can test how parallel your igraph is by increasing the number of threads. You can set the number of thread (using the Threads Panel) to a larger number, say 16. Then click the button. Now we can simulate the behavior of this igraph when there are 16 processors available. Run the profiler again by clicking the button. The profiler window will come up again when the igraph has finished: Profiling with Multiple Threads This time there are columns labeled Thread 0, Thread 1, etc., up to Thread 6. Even though there are a total of 16 threads available, only 6 (0-5) threads can be used. This represents the maximum amount of parallelism that this particular igraph can take advantage of. The Parallelism field in the Profiler Metrics panel (View/Advanced... menu item on Profiler window) gives you an estimate of how much parallelism you may expect to see if you have multiple CPUs. If this number is 2, for example, then it means that the igraph may theoretically run twice as fast (or in half as much time) if you have a computer with 2 or more CPUs. In reality, you will never quite reach the Parallelism metric because of operating system overhead. With the Check Gear igraph, the Parallelism is about 2.3, even though there are 6 active threads. The reason for this is obvious if we study each of the Thread N columns in the profiler window. Many of the threads are not very busy. Of the 6 active threads, only four are comparatively busy. Therefore, you probably only need about four CPUs to realize most of the parallelism inherent in this igraph. 32 Adjusting the Number of Threads Utilization of multiple CPUs is automatic. WiT detects the number of processors on your system and starts an execution thread for each processor. An additional thread is also added for each library context (see Programmer Manual). You can force WiT to start a fixed number of threads: 1. 2. 3. 4. Select Advanced Options from the Tools menu. The Advanced Options panel comes up. Click the button for Threads. The Threads Panel comes up. Uncheck the Auto check box, then enter the desired number of threads you want WiT to work with. Click the button. The number of threads is activated immediately. Changing No. of Threads for Profiling To revert to automatic thread creation, check the Auto check box on the Threads panel. Advanced Igraph Concepts Igraph Design Techniques A number of techniques are important for building igraphs which are easy to understand. A readable igraph is easier to maintain and ultimately will save you time and effort, especially if you need to share igraphs among a work group. Some of these techniques are in fact necessary if you want to convert an igraph into program code, which can be generated automatically with WiT Studio. If you have experience in writing programs with traditional languages such as C or BASIC, you can compare the concepts presented in this chapter to traditional structured programming techniques. Just as you can easily create practically incomprehensible programs if you do not follow common structured programming practices (which often are not enforced by the programming language), so too you can create incomprehensible igraphs. Indeed, because igraphs are inherently parallel and are two33 dimensional, a poorly structured igraph can be more difficult to understand than a poorly written program. Placement of Operators and Links Since execution in an igraph can literally proceed in any direction, care must be taken so that the execution sequence proceeds naturally. Usually from left to right and from top to bottom. Not following a consistent placement strategy would be like using gotos in a conventional programming language. The algorithm may work, but it will be almost impossible to understand and maintain. The following figure shows a functionally correct igraph. But it is difficult to understand. Poor Placement of Operators 34 A simple rearrangement of operator icons and links makes the intent of the algorithm much more obvious: Good Placement of Operators Meaningful Icons and Names Just as meaning identifier names are essential in a conventional program, meaningful operator names and link names are equally important in an igraph. Igraphs of course can further benefit from meaningful operator icons. Besides coming up with interesting and informative graphics, you can choose the appropriate icon size (e.g. larger icons for more complicated operations) and port arrangements to enhance icon appearance. Use of Blank Spaces Just as blank lines in a conventional program file can greatly enhance the organization of related code, blank areas between groups of related operators also significantly improve the readability of an igraph. Use of Space in an igraph 35 Minimize Link Crossovers If possible, try to avoid drawing a link which crosses over another link without a connection. Such constructs make an igraph confusing. By flipping operator orientation and using subgraph operators, link crossovers should be rarely needed. Sloped Links Especially when branching off from or merging into a link junction, the use of sloped (non-ninety degree) links often improve igraph appearance because the sloping links suggest the direction of data flow and the branching or merging behavior. However, this may be a personal preference. Use of Sloped Links Annotations Annotations on an igraph are similar to comments in a conventional language. Even though meaningful icon designs and relevant operator and parameter names can substantially improve igraph readability, there is no substitute for the liberal and sensible use of annotations. Highlighted backgrounds, pointers with explanations, or short textual descriptions, can really make an igraph much easier to understand. Subgraphs Although WiT is designed to handle very large igraphs, trying to fit too many icons and links onto one screen can make an igraph look congested and difficult to understand. Liberal amounts of space is essential to a good igraph, which unfortunately will also take up valuable design space. Therefore, whenever possible, group functionally related operators and make them into a subgraph. There is practically no execution overhead involved in executing subgraphs. They make an igraph more compact and easier to manipulate, and their use is similar to the concepts of top-down design and stepwise refinement in conventional programming languages. 36 Goto Operator While the goto statement is almost to be avoided at all costs in a conventional language, gotos in an igraph sometimes can be used to improve appearance. A long link on an igraph can often be more confusing than a goto and label pair, particularly if the long link needs to cross over other links. However, if you use subgraph icons effectively, it is possible that you can avoid gotos or long links in most circumstances. Connecting an Operator to Itself In general, loops are perfectly acceptable in an igraph. However, you should not connect an output of an operator directly (i.e. no other operators in the loop) to one of its own inputs. An example of such an unsupported construct is shown below: Illegal Loop Such a construct is a problem because operator execution conceptually proceeds as follows: 1. 2. 3. 4. The inputs are used to produce the outputs, if there are errors, exit. Try to send the outputs to all descendants. If successful, goto 4, else goto 2. Delete the inputs and exit. If you connect an output directly to one of the inputs, then step 2 will always fail, since a token can only be sent to a port if that port is empty, but we are sending the token to our own input ports, and the input ports are not cleared until step 4 is executed. In practice, you should not do this anyway since that would result in an infinite loop. If you really want an infinite loop (for use as a free running demo, for example), then you should do something in the loop. It should be noted that if there is a link junction at the input, then the construct would be valid and even useful. The link junction provides a storage place for the output token so that the operator can operate on one token while the output can be stored in the junction. Legal Loop 37 Common Control Constructs Most users of WiT will probably have some programming background. So it is worthwhile to look at what some of the commonly used constructs in a procedural language look like in the data-flow environment in WiT. Adhering to these constructs not only make igraphs look more organized, but it is absolutely essential if you want to generate programming code from an igraph. Because an igraph link can only carry one data object, the functions (operators) controlled by controlflow operators can only have single inputs and single outputs. If multiple inputs or outputs are required, then they should be packaged into a new object type or as a vector of objects. If-Then-Else The igraph construct: represents the following C if-then-else construct: if (condition) result = op1(data); else result = op2(data); op3(result); 38 For Loop The igraph construct: represents the following C for construct: value1 = op1( ); for (i = 0; i < 3; ++i) { value2 = op2(value1); value1 = value2; } op3(value1); While Loop The igraph construct: represents the following C while construct: condition = op2( ); value1 = op1( ); while (condition) { condition = op3(value1, value2); value1 = value2; } op4(value1); Sequencer The igraph construct: 39 represents the following C construct: for (i = 0; i < objVecSize(objVec); ++i) { value1 = getElement(objVec, i); op1(value1); } Collector The igraph construct: represents the following C construct: for (i = 0; i < objVecSize(objVec); ++i) { value1 = getElement(objVec, i); value2 = op1(value1); putElement(newObjVec, i, value2); } op2(newObjVec); 40 The Scheduler WiT uses a scheduler to decide which operators to run on which servers to maximize parallelism but maintain correct execution order. Most users do not need to be concerned about how the scheduler works or even be aware that there is a scheduler at all. However, for advanced users who want to understand the inner workings of WiT in order to optimize performance, a full understanding of how the scheduler works can be helpful. Scheduling Strategy Operators are placed on a ready list whenever they are ready to be executed. The scheduler picks up operators from the ready queue in a first-in first-out fashion. When multiple remote servers with different operator libraries are active, the scheduler loops through the server list and attempts to assign an operator from the ready queue to each idle server. Therefore, it is possible for operators to be executed in a different order than they are placed on the ready queue because their servers are different. An operator becomes ready whenever all its inputs are available. An operator can also become ready after any of its outputs are unblocked (see below), or when an interactive operator (such as getData) has returned from receiving user inputs. After execution, an operator tries to send all its outputs to its descendants. However, it may not be successful because some of its descendants may still be processing previous inputs, and are not ready to accept any new inputs. In this case the ancestor operator becomes blocked. When an operator has finished execution, it will clear its inputs and try to wake up any direct ancestors that were previously blocked. You can have more than one output connected to the input of an operator. In this case, whichever object arrives first at the port will be accepted, and all other data inputs will be blocked until the operator has consumed the first data object. Data Transport For most applications, all WiT operators are executed directly by WiT or by libraries. But when an igraph has operators that are executed remotely on eWiT or on hardware that contains local memory, data transport is sometimes necessary. eWiT and libraries that manage hardware are known as remote servers in WiT, or often just servers for brevity. Data objects generally are not transported between WiT and remote servers or among the servers themselves unless it is necessary. Often an entire algorithm, including input/output operations, can be executed on a single server without any data transfer at all. Data transfer is necessary when the object needs to be displayed, or when the server that has data does not support a required operation. 41 When multiple servers are involved, the scheduler maintains information about where each data object resides. When an operator needs to be scheduled, the scheduler assigns it to the available (not busy) server which requires the least amount of data transfer. When a link branches into parallel branches, copies of the data object will be physically copied to each remote server which needs it. But after this initial copying, the servers will be able to execute in parallel. 42 Operators Operators in WiT are analogous to functions in a programming language. The connectivity of operators is analogous to the sequence of instructions within a conventional program. Conventional computer language instructions can only be arranged in a linear fashion (at least visually). But operators in a WiT igraph can be arranged in different topologies, making igraphs much better for representing parallel algorithms. Invoking Operators The first steps required to create an instance of an operator are almost the same in graph and script modes: 1. 2. 3. 4. 5. Bring up the Operator Explorer from the Windows menu. Choose the All library on the left side of the Explorer. Or, if you know the library where the operator belongs, choose that library. Locate the operator you want on the right window of the Explorer. If you are running in graph mode, press the left mouse button at the operator you want, then drag the operator onto the igraph workspace. Release the mouse button when the operator is at the position you want. If you are running in script mode, double-click the operator in the Operator Explorer. The operator property panel will come up automatically. Make any desired changes to the parameters, then click the button. The operator is executed and its results, if any, are displayed on the workspace cards. If you click the button instead, the operator will not be executed. After you click , the operator starts running and the status indicator changes to . You must wait for the operator to finish executing (the status indicator changing to ) before invoking the next operator. 43 Invoking an Operator If you prefer, you can also type in the operator name directly in the Name field. You can use the ‘*’ wild card character. As you type, the operator list (the one on the right hand side) is updated to show the list of operators which match the characters typed so far. You can scroll this list at any time to locate the complete name of the operator you want. There are some features in the Operator Explorer which help the selection of a desired operator: • • You can invoke an operator by clicking once at the icon, then hit the button. To find out which library an operator belongs to, point to the operator icon in the Operator Explorer, then press and hold the right mouse button to bring up the pop-up property menu. Select Go to. The library from which the operator comes from is selected on the left of the Operator Explorer. Getting Help for Operators There are a number of ways you can get help for an operator: • • • • Point at an instance of the operator in the Operator Explorer and hit the F1 key. Point at an operator in the Operator Explorer, bring up the property menu, and select Help. Point at an instance of the operator in an igraph and hit the F1 key. When the property panel of an operator is visible, click the button. Getting Help for an Operator Port Sometimes an operator has so many ports that it is not obvious what each port does. Usually the graphics in the icon indicate the functions of the ports, but when there are many ports, attempting to 44 show port functions graphically may result in extremely complex looking icons. That would defeat the purpose of icons, which should be something simple and easy to recognize. If you point the mouse at an operator port in an igraph and keep the mouse there for a few seconds, a tool tip window will come up to show you information about the port. The information includes the operator and port name, and the type of object that the port is expected to receive or produce. Operator Port Tool Tip Operator Parameters Each operator may have a number of parameters which control its execution, e.g. the width of a filter, name of file to read, etc. A parameter must have a name, e.g. filename, width. On invocation of an operator, a property panel is presented for you to specify its parameters. On the property panel, each parameter is listed with its name followed by a data entry area such as a slider or choice list for you to enter a value. In addition to parameters specific to the operator, the property panel present standard properties which apply to all operators. These properties are for things such as execution control and visual appearance of the operator, and are different in graph and script mode. Operator specific parameters are identical in either mode. Simple object types such as integers, characters, or strings are displayed and edited directly on the operator property panel. Complex objects or multi-dimensional (array) parameters are presented with a button: Complex Operator Parameters Complex and array parameters cannot be edited directly on the operator property panel. Instead, you must click the button. For array objects, an array editor will come up: 45 Array Editor for Array Parameters For complex object parameters, an Object Editor will come up when you click the Object Editor appears differently for each type of object. Object Editor 46 button. The Parameter as Input Any operator parameter can be converted into an input, which can then be fed by outputs from other operators. This is a very useful feature because it allows parameters to be computed dynamically. The procedures for converting a parameter into an input is different for graph and script mode. Special Operators Besides the mechanics of building igraphs, you will need to develop the knowledge of how problems are solved using the collection of operators and objects available in WiT. In addition to the usual image processing operators such as convolution and thresholding, there are some special WiT operators which will make igraph design much easier. These include all the obvious flow control operators, such as if, sequencer, etc., as well as some commonly used operators which are quite uniquely WiT. Some of these operators are described in detail here. More information can be found in the Operator Reference Manual. display The display operator creates a pop-up frame containing the data of the object received at its input port. If the object is an image, then the pop-up will present a rendered image. If the object is not an image, then display will pop up a frame with text showing all the pertinent data contained within the object. When data arrives at a display operator, the data is shown in a detached window. Display detects the type of the input object. If it is an image or a vector of images, then it brings up an image window, otherwise it brings up a general object window. The position of the pop-up window is controlled by the Placement option in the Advanced Options panel. The default is to tile windows on the screen. You can override auto placement by specifying an explicit position for the X and Y parameters in the Placement sub-panel of the display property panel. The name of the pop-up display can be set using the name parameter. Operators with the same name will display objects in the same pop-up window, with the new object replacing any existing displayed object. 47 For images, the size of the pop-up window is the actual size of the image. For general objects, the size is just big enough to show the entire object with the default font. If the object size is larger than the screen, then the window size is limited to the screen size, and scroll bars appear automatically. You can also specify a maximum size with the MaxW and MaxH parameters in the Placement sub-panel. MaxW and MaxH only affects the initial window size, they do not limit any subsequent manual resizing of the object window. More controls are available from the pop-up menu (press right mouse button inside window). Pop-up menus are different for image and non-image data objects. Display Operator Properties Main panel: Name Name to be used on the window title. When a new object reaches a display operator, all existing data object windows are searched to look for a matching name. If an existing object window has the same name, then the new object is displayed in the existing window. This way you can track data changes without having too many windows. If no matching window name is found, a new window is popped-up. 48 Placement sub-panel (applicable only to non-image data): Placement If Fix position is checked, the parameters X and Y are used to position the window. Otherwise, the current automatic window placement strategy is used to position the window. If Max size is checked, then the parameters MaxW and MaxH are used to limit the maximum size of the window. If the object requires a window larger than the maximum size, then scroll bars will appear. If Min size is checked, then the parameters MinW and MinH are used to force the window to be at least the minimum size. If the object is an image or image vector and it requires a window smaller than the minimum size, then the pixel sizes will be scaled so that the window is at least as large as the minimum size. X The X (horizontal) position of the window on the screen, if Placement has Fix position checked. Y The Y (vertical) position of the window on the screen, if Placement has Fix position checked. MaxW The maximum width of the window, if Placement has Max size checked. MaxH The maximum height of the window, if Placement has Max size checked. MinW The minimum width of the window, if Placement has Min size checked. MinH The minimum height of the window, if Placement has Min size checked. Image sub-panel (applicable only to images): Range The valid range for the pixel values. For example, when images are digitized from a 12-bit source, then each pixel may be represented as an unsigned 16-bit integer, but only the lower 12-bits are used. So the valid range in this case should be 0-4096. If Range is set to Auto, the range is computed to be the minimum and maximum pixels values in the image. Properties RangeLow and RangeHigh are disabled. If Range is set to User, the values specified for RangeLow and RangeHigh are used. RangeLow The lowest valid pixel value. See Range above. RangeHigh The highest valid pixel value. See Range above. Equalize The range of pixel values that will be stretched to map to the black and white levels of the display. The low end of the equalization level will be mapped to black on the screen, and the high end of the equalization level will become white. Pixel values in 49 between are interpolated linearly. Pixel values less than the equalization low value will become black. Pixel values greater than the equalization high will become white. If Actual is chosen, all pixels in the image are scanned to compute the minimum and maximum values. The equalization values are then set to the minimum and the maximum actual pixel values. If User is chosen, the values of parameters EqLow and EqHigh are used to set the equalization limits. If Max is chosen, the Range low and high values are used for the equalization limits. EqLow The equalization low value, used only if Equalize is set to User EqHigh The equalization high value, used only if Equalize is set to User XScale The scale of each pixel in the X (horizontal) direction. A larger value means the image will appear bigger. YScale The scale of each pixel in the Y (vertical) direction. A larger value means the image will appear bigger. Inspect If X-Profile is checked, a profile plot along the X-axis will be displayed along with the image. If Y-Profile is checked, a profile plot along the Y-axis will be displayed along with the image. If Magnifier is checked, the pixel value magnifier window will be displayed along with the image. Track If Mouse drags is selected, profile plots and magnifiers will track pixel values only when dragging the mouse (i.e. left mouse button down). If Mouse moves is selected, then profile plots and magnifiers will track pixel values all mouse movements whenever the mouse is inside the image window. Colormap Applicable only to grayscale images. The meaning of each map is the same as in the image property panel. The Shared choice is obsolete and should not be used. If Custom is selected, a valid color map file name must be specified for the ColormapName parameter. ColormapName The name of the color map file to be used if Colormap is set to Custom. Text sub-panel: 50 Format If Yes, the data is displayed with field labels, indentations, and new lines. Otherwise only the values are displayed. Displaying with no format is more suitable for simple values such as single integers or strings. FontFamily The font used to display the text, e.g. Arial, Times, Helvetica. Style Choose one of Normal, Italics, Bold, and Bold-Italics. Size The size (height) of each character in pixels. TextRed The red component of the color used for the text. TextGreen The green component of the color used for the text. TextBlue The blue component of the color used for the text. BackRed The red component of the background color. BackGreen The green component of the background color. BackBlue The blue component of the background color. Image Properties Panel Size/Type Original width and height of image, and the type of each pixel. Range The pixel value range used to determine the display color of each pixel. The range defaults to the actual range of pixel values in the image. A pixel with value less than or equal to the low end of the range is displayed in black in a grayscale colormap or the bottom color in other colormaps. A pixel with value more than or equal to the top end of the range is displayed in white in a grayscale colormap or the top color in other colormaps. Pixel values in between are interpolated linearly between the top and bottom colors in the colormap. The pixel range can be changed by clicking the button. This brings up a Pixel Range panel. Pixel scale Screen size of each image pixel. Click the Frame size The size of the frame in screen pixels. You can resize the frame by using the resize corners on the image window, or click the button to enter an exact size. Image displays support scroll bars. Apply to If Current is selected, property changes are applied to the image display which has the focus, the name of which is displayed on the title bar of the image property panel. If button to change. 51 All is selected, property changes are applied to all existing image displays. If Selected is chosen, property changes are applied to selected image displays. If Except selected is chosen, property changes are applied to all image displays except the selected ones. Mouse moves Normally when inspect is turned on (profiles or magnifier), data values are only updated when you click the left mouse button or drag the mouse. With Mouse moves checked, data values are updated whenever the mouse moves. Inspect If X or Y is checked, an image profile plot is displayed in a separate window. For color or complex images, multiple curves are simultaneously displayed. The profile plots can be manipulated using the pop-up property panel (pressing right mouse button inside the profile window), same as the graph operator. If Magnifier is checked, a pixel magnifier which displays exact pixel readings is displayed. The Magnifier uses the Array Editor to display exact pixel values. By default, the pixel magnifier comes up showing a 3x3 area centered on the pixel the mouse is pointing at. The format of the values shown inside the magnifier depend on the type of the image. Color Map Applicable only to grayscale images only. Three colormap types are available: 1. 2. 3. Image index 52 Grayscale: Consists of different shades of gray. The number of shades can be user configured. Pseudo: Grayscale values in an image are mapped to a set of colors like a rainbow. Pseudo-color is useful for enhancing the contrast between different parts of a grayscale image. Custom: Bring up a Map Editor which allows you to specify interactively the mapping of each pixel value to a particular color. Applicable to vector of images only: select which image in the vector to display. Refresh Redisplay the image. Useful when parts of the image are not displayed properly due to actions from other windows. Save... Save the current image as a WiT object to a file. A file dialog will come up. The saved object can be read by the rdObj operator. Load all Applicable to a vector of images only. A vector of images is cached so that the scroll bar can be used effectively to quickly animate different images within the vector. Normally this cache operates like most caches: an image is placed in the cache only when it has been accessed, i.e., when it is displayed. This can create some annoying initial delay when using the scroll bar. The Load all button allows you to force all the images in the vector to be loaded in the cache, provided that the cache size is not exceeded. No harm is done if the cache is not large enough. In that case the cache will be filled to capacity. Consideration must be given to memory consumption. Images typically take up a large amount of memory. Loading a vector of images can cause severe performance degradation to WiT and other programs, due to excessive swapping of RAM data to and from disk. If you do not need to access all components of the image vector, then it may be better to let the cache load the images on demand. The cache is flushed whenever the image scale has changed, such as when you scale an image using the resize corners. If you wish to pre-load all images in the cache, then you will have to click the Load all button every time you resize the image window. The demo igraph collect demonstrates the use of image vectors. 53 Pixel Range Panel The Image Pixel Range panel is used to control the range of pixel values that WiT considers as valid for display purposes. Any pixels with a value lower than or equal to the minimum will be shown as black. Pixels higher than or equal to the maximum will be shown as white. Type Max Maximum range allowed by image type, e.g. 8-bit is 0 — 255. Actual Actual pixel range of all pixels in the image. User User specified range. Use Min and Max to enter the values. Min Minimum valid pixel value. Max Maximum valid pixel value. Image Menu Select Select the image for printing or group adjustments. Properties... Bring up image property panel. Zoom Start zoom mode, cursor will change to View all Display image in its entirety, sized to the shape of the window. Useful after panning or zooming. Normal size Resizes image so that one image pixel is displayed as one pixel on the screen. Set cursor... Sets the mouse cursor to an exact position within the image. 54 General Object Menu Select Select or deselect the window for printing. Font... Change the font used for this window. Save as Text... Save the object to a file in text format, with the line breaks and indentations as displayed. Save as Object... Save the object to a binary file in WiT format. The file can later be read by rdObj. graph The graph operator accepts either a single vector or compound vector (vector of vectors) of values for plotting single or multi-line graphs. The operator can generate line graphs, bar charts, histograms and scatter plots. The graph operator accepts vectors of integer points or float points, or vectors of integer or float scalar numbers. Point input data is plotted using the (x,y) coordinates from the data. Scalar data is plotted using the vector index (starting from 0) as the x coordinate and the element value as the y coordinate. It is also possible to plot a multi-line graph from a compound vector (vector of vectors) or from multiple individual vectors (described below). 55 When input data arrives, a graph frame pops up, displaying the graph as specified by the operator's parameters. A properties panel can be invoked from the pop-up menu inside the graph region, and can be used to change the method of displaying the graph data. Pressing the left mouse button while the cursor is on the graph gives the exact cursor position in graph coordinates. The graph can be scaled and panned in the same manner as an igraph. Graph Operator Properties Main panel: grTitle The title of the graph. If there are multiple graph operators in an igraph, you can send all the plots to the same graph by setting the grTitle of the operators to the same name. Also, if you have set Auto clear in the Options panel (Section 14.16) to false, then you can plot curves from different igraphs to the same graph, provided that the grTitle are set to the same name. name The name of the curve or curve set. If the input is a list of curves, you can enter multiple names. E.g., if you are sending a vector of 3 curves, then you can set the name parameter to apples oranges "a complex name" then the curves will be labeled accordingly on the graph. If only one name is specified, then each individual curve is labeled with this name plus an identification number, e.g. curve-1, curve-2, etc. Options sub-panel: type The type of curve to plot for the data set. cumulative If No, then every time a data set is sent to the graph, all previous curves are deleted. If Yes, the new data set is added to the graph as a new curve. The X and Y axes are recomputed to accommodate all data sets, if the scales are set to Auto. showDataPts Curves plotted as type Line are plotted by joining data points with line segments. If showDataPts is set to Yes, then the original data points are shown as dots on the line. This parameter has no effect on other curve types. showLegend If Yes, a curve legend is shown on the graph. legendPos 56 Enabled only if showLegend is Yes. Specifies the position of the upper left corner of the legend box within the graph. XAxis and YAxis sub-panel: xaxis/yaxis The label on the X/Y-axis. axisXScale/axisYScale If set to Auto, then the range of the X/Y-axis is automatically calculated to just contain all the curves in the graph. The tick marks are calculated so that the labels are nice round numbers. If set to Manual, the range specified in the xaxisRange/yaxisRange parameter is used, regardless of the actual data range of the curves. xaxisRange/yaxisRange The range of the X-axis. Applicable only if axisXScale/axisYScale is set to Manual. The format must be two numbers separated by a space: minimum maximum, Examples: 0 100, -0.01 2.5 xShowTicks/yShowTicks If Yes, tick marks are shown along the x/y-axis. Otherwise not shown. Placement sub-panel: Placement If Fix position is checked, then the X and Y values below will be used to position the graph window. Otherwise, the normal placement strategy (Section 8.12) is used to position the graph. X The horizontal position of the upper left corner of the graph window, if Placement is Fix position. Y The vertical position of the upper left corner of the graph window, if Placement is Fix position. width Width of graph window. height Height of graph window. 57 Graph Property Panel Curve type The type of curve to plot for the selected data sets. Show data points If checked, and if a curve is plotted as a line, then the actual data points are plotted on top of the line. No effect on other curve types. Show legend Show a curve legend on the graph. You can drag the legend to anywhere you want within the curve area. Show grid Show a grid on the graph. Show leads If Show leads is checked, leads will be drawn from the position where you click the left mouse button (see Section 9.4.6) to the axes. Select all Select all curves. Delete curve Deselect selected curves. Show label Show the X or Y axis label. Show ticks Show ticks on the X or Y axis. Range Allows you to specify the exact axis range for the X or Y axis. Displaying Exact Coordinates You can display the coordinates of various positions on the graph: click the left mouse button at the position you want, the exact coordinates of the mouse position are shown on the graph. If you drag your mouse on the graph, the coordinates will be continuously updated. The reported position will snap to an actual curve data point if it is close enough. 58 Curve Types Data sets can be plotted in any of the styles listed below. A data set must be selected before its type can be changed. • • • • • Line Histogram Bar chart Scatter plot Invisible Input Types The input to graph can be any one of the following: • • • A vector of integers or floating-point numbers: each item in the vector is plotted against its position within the vector. A vector of points (ordered pairs): the y value of each point is plotted against its corresponding x value. A vector of vectors of integers, floating-point numbers, or points: each vector is plotted as a separate curve within the same graph. When multiple data sets (curves) are shown, different colors (on color displays) or line styles (on monochrome displays, and when graphs are printed on a monochrome printer) are used to distinguish between the sets. The legend panel identifies the curves. Multiple Curves As in displayed images, if two graph operators have the same title, then the same window is used. When a new set of data is sent to a graph operator, the behavior depends on the cumulative parameter. Selecting Curves A data set is selected by clicking the left mouse button at its legend. Check Show legend on the property panel if you do not see the legend. A selected curve name is shown in bold face in the legend. You can add to the selection by using the middle mouse button. You can also use the Select all button on the property panel to select all curves. Zoom and Pan Zooming follows the usual procedures using the Zoom item from the pop-up property menu. Tick marks on the axes are automatically recalculated after zooming. 59 To pan, point the mouse somewhere on the X or Y-axis, then press and hold the left mouse button. As you drag, the graph is panned. Memory and Counter Some operators, such as memStore and counterStep, uses names to refer to global data objects. memStore uses names to refer to global storage locations. counterInit uses names to refer to a counter. For the same object type, the same name refers to the same object, regardless of where and how many times the name is referred to in an igraph. Different object types with the same name refer to different objects. For example, if an igraph has a memStore operator with the memory name "mem", then anywhere in the igraph where a memRecall is used with the memory name "mem", the same memory location will be used. Likewise, if an igraph has a counterStep operator with the name "count", then anywhere in the igraph where a counterStep is used with the name "count", the same counter will be stepped. But if a memStore operator has the name "x", and a counterStep operator in the same igraph also has the name "x", then the memStore and counterStep operators refer to two completely unrelated objects. When names are used in subgraphs, you can use a syntax similar to file directories, using slashes and dots. For example, to refer to an object at the same subgraph, you can simply use a name, such as "foo". If you want to refer to a object defined in a subgraph named "sub", then you can use a name like "sub/foo" (both forward and backward slashes can be used). To refer to a name defined in the graph above the current level, use a name like "../foo". If the name is defined two levels above, use something like "../../foo". Or you can specify an absolute path name at any subgraph level, like "/sub1/sub2/foo". Processing Data Fields GetField and PutField WiT data objects often contain many fields. Often it is desirable to operate on specific fields using WiT operators. For example, the Point object has an x and a y field. You may want to extract the x field to be used in subsequent processing, or you may want to replace the y field with a value computed from other operators. To access data fields, two operators called getField and putField are used. The getField operator takes any object, extracts the requested field by name, and delivers this data as a new object. The putField operator performs the reverse action. For example, suppose we want to increment the x value of a Point object 2. First we feed the Point object to getField with its field parameter set to x. The output of getField will be an integer corresponding to the x field in the point. This integer is incremented using the calc operator, with x fed to both inputs, and using the expression A+2. To update the x field in the original point object, feed both the original point and the new x as inputs to putField, with the field name set to x. The igraph looks as follows: 60 Field Manipulation Operators Field Names To extract a particular field for an object, you must first know its name. Field names of all the standard WiT object types are listed in Appendix Object Field Names. The field parameter in getField and putField has a button that allows you to interactively select a field using the Object Explorer. The Object Explorer can also be displayed from the Tools menu in the main WiT window, if you just want to browse objects without using getField or putField. Field Names of Nested Objects A nested object has fields which refer to other objects. Nested objects help to break up and reuse common data required by many operators. For example, the Geometry object is used to store data which describes a variety of graphical primitives such as lines, polygons, points, rectangles, circles, and text. The Geometry object fields are: Field Name Description type type of graphical primitive plist vector of points text a Geometry text pointer This object has a reference to another object called Geometry t If the type field indicates that the Geometry object is a graphical text string then the text field is used to access the data in the Geometry text object. Otherwise, the Geometry text field can be NULL. For example, consider the Geometry object below: Geom with Text Primitive 61 This display is typical for a general object in WiT. The first name, Geometry, defines the object type. This is not a field name. The field names are indented and listed along with their values. Indentation occurs whenever a nested object or vector is encountered. In this display, the type field is shown followed by the plist vector. The type and size of the vector is shown next to the field name, e.g. Real point[1] in this example. Another indentation follows to display the elements in the vector. Elements are displayed with an index number, e.g. ‘0:’, then their field names and values, e.g. x 95 y 111 (a Real point object contains two floating-point fields x and y). The text field is a pointer to a Geometry text object. The '+' symbol indicates that this pointer is non-NULL. The fields data (the text string value), fontFamily, fontStyle, and fontSize belong to the Geometry text object. Various pieces of information can be extracted using getField given this object. Here is a table listing a few possibilities. Extract Description Field Syntax Output Type Get the first x coordinate from the point list plist[0].x float Get the third letter from the text string text.data[2] char Get the number of points in the point list plist.d0 int Get the font size text.fontSize int Get the first coordinate plist[0] Real point The Geometry object is used by many other objects such as the Graphic, Line, and Edge. The benefit of reusing an object is that once you master how to use getField and putField for the Geometry object, then any other objects using Geometry will be manipulated in the same way. The Graphic object, for example, contains the Geometry object to describe a graphical primitive but adds extra information such as fill and pen colors. The Line object contains the Geom object to describe the two points of a line but adds extra information such as line distance and angle. The Edge object contains the Geometry object to describe the position of an edge (a single point) but adds extra information such as edge direction, slope and level. Specifying Fields for Multi-Dimensional Data GetField and putField is especially powerful when processing multi-dimensional data (vectors and images). You can access the size of a 1-D object (vector) using the d0 field (or size for backwards compatibility with older versions of WiT). Or you can access the width and height of an image (2-D object) using the d0 and d1 fields (or W and H for backwards compatibility). In general, you should not change d0 or d1 with putField. Re-dimensioning a multi-dimensional object requires reallocation of data storage. Merely modifying the size fields is not sufficient and is dangerous. But you can always extract d0 or d1 with getField safely. You can extract or modify multiple elements in a multi-dimensional object easily with getField and putField. For example, to extract the npixels field of each Blob feature element in a Blob feature vector, use getField and set the field parameter to [*].npixels. The wildcard character '*' tells getField 62 that the field is to be extracted for each element. The result is a new vector containing elements with the same type as npixels, so the output is a vector of integers. This powerful concept can save considerable effort in repackaging data for later manipulation. You can also specify a range of elements, such as [5-9].npixels. The range selection technique can also be used for nested fields. For example, to extract all the x fields of the plist field in a Graphic object, you can set the field name to geom.plist[*].x. You can operator on 2-D objects in a similar fashion. For example, to extract the sub-image from rows 5 to 10 and columns 19 to 33 of an unsigned 8-bit image, set the field to [19-33][5-10]. Notice that the first dimension, d0, corresponds to the width of the image. This may be a bit confusion because image sizes are typically expressed in [width][height], but in most programming languages, such as C, arrays are represented such that array column is the lower dimension, so that 2-D arrays are represented a s [row][column]. GetField and putField uses the programming (C) style of representation, primarily because images are just one particular type of 2-D arrays. When dealing with more general 2-D arrays, the C style is more consistent. Processing Object Vectors Sequencer The sequencer operator is used when the data elements require significant processing or must be processed by a group of operators which only work on single objects. An example of using the sequencer effectively is when a large group of files must be read in from disk and displayed in separate windows: Sequencing a vector The dir operator generates a list of filenames. The sequencer sends one at a time to rdImage which loads the image from disk. Here the filename parameter of rdImage has been converted to an input. The display operator uses the same window for new data if the name parameter is the same. In order to display each data file in a separate window, we need to change the name parameter of display for each data file. The counter produces a count value which is an integer. The cast operator is then used to convert the count to a string. The name parameter of display has also been turned into an input so that we can feed the output of cast to it to create a unique name for each data file. 63 Partition and SortObj When you need to process elements in a large vector, then using the sequencer to unravel the vector could be inefficient depending on the level of element processing. Instead there are operators to provide high-level operations specifically to process vectors of this sort. The partition and sortObj operators provide an efficient way of splitting or sorting vectors based on the values of field names in each element. The partition operator receives a vector and performs a comparison with one field in each element to split the vector into two groups. The group that satisfies the comparison is produced as the top output. The group which fails becomes the bottom output. For example, you can use partition for processing Blob feature vectors to remove connected regions which fail to satisfy a series of comparisons. The sortObj operator can sort a vector based on the value of a field in an element. The field parameter value required by both the partition and sortObj operators use the same syntax for defining field names than b>getField. Calc and Cast The calc and cast operators can process vectors. Only simple vectors of integers, floats, strings, etc. can be processed. Calc performs arithmetic on each value in a vector. Cast converts the data type for each element. C Code Operator The cCode operator gives you a window to type in a few lines of simple C code. The purpose of this operator is to allow users to perform simple calculations in C instead of using a combination of WiT operators. Used properly, the cCode can simplify many otherwise awkward looking igraph structures. The source code for a cCode operator is stored directly in the igraph, and all the cCode operators in an igraph are compiled automatically when the igraph is saved to a library (DLL) with the same name as the igraph, and saved in the same directory. You must have a C compiler installed on your computer to use cCode. Currently only Microsoft Visual C is supported. The cCode should not be considered an alternative for creating full-fledged operators with many lines of code, because the support mechanism for cCode does not facilitate debugging. For developing such operators, the usual procedures described in the Programmer’s Manual should be followed. Operator Icons An operator icon can be any size. It can have any number of input ports, outputs ports, and parameters. Normally, an operator is shown as an icon with the operator name at the top, parameters at the bottom, input ports on the left, and output ports on the right. The icon may or may not have a 3-D look. 64 All standard WiT operators come with meaningful icons. However, when you create new subgraph or primitive operators, you may want to create your own icons. Or you may want to customize icons for existing operators to enhance the look of your igraphs. WiT icons are stored in 16-color BMP format. Simple designs and changes can be conveniently done within WiT with the WiT icon editor. However, you may want to make major changes with a more sophisticated icon editor, such as those which come with compiler SDKs. Icon files are stored under the icons directory of the library of the project. Take the operator conv2d as an example. Conv2d belongs to the filter library, which belongs to the standard WiT operators project, ops. So the icon file for conv2d can be found at: $WITHOME\ops\filter\icons\conv2d.bmp See the Programmer’s Manual for information about making an icon for a new operator (as opposed to changing an icon for an existing operator). Icon Cache Because of the large number of operators that WiT supports, reading in all the icons as individual files can take considerable time. For this reason, WiT maintains an icon cache. Each time WiT starts up and detects new operators, their icons are parsed and stored in the cache, so that on subsequent runs of WiT the icons can be read from the cache. If you use the WiT icon editor to modify an icon, the icon cache is invalidated automatically and WiT will re-read all icon files the next time it is started. However, if you modify an icon without using the icon editor, WiT will not know about the change and will still use the old icon from the cache. To force WiT to re-read icon files, use the View/Reload menu item on the Operator Explorer. Multiple Implementations When the same operator is supported by two or more different implementations (libraries or contexts) in a configuration file, a server type property in the parameter panel will appear for each operator selected from the library. This permits you to decide where an operator is to be executed. For example, suppose you have a different algorithm for the histogram operator implemented in a library called myLib. Then the histogram operator will have two implementations: one in the standard Measurement library and another in myLib. The property panel for the histogram operator would then have a Server item: 65 Multiple Implementations You can select either Any, Measurement or myLib. If you select Measurement, then WiT will run the operator only using the implementation in the Measurement library. If you select myLib, then WiT will only use the implementation in myLib. If you do not care which implementation to use, select Any. In this case WiT is free to choose whichever implementation is available. When Any is selected and all the implementations are available, the server whose name appears first in the Server list will be selected. Implementations realized as pure software libraries are in general always available. However, some implementations may involve hardware. So under some circumstances an implementation can become busy. A common example is a library that supports a frame grabber. The operator acquire is implemented by the hardware and until the acquisition is complete, the library is busy and no more operators can be executed by it while it is busy. WiT automatically postpones execution of any operators which require a busy library until the library is available again. Libraries WiT comes with a large set of standard libraries. They are grouped according to function in the Operator Explorer and also in their file arrangements. The following is a list of libraries with a short description for each. In addition, the SmartSeries libraries offer higher-level application oriented algorithms which can cut down your development time even more. Refer to the Operator Reference manual for details. Standard Standard libraries Blobs Blob analysis. The library includes operators that extract and process blobs, which are connected components in binary or labeled images, and a set of features of the blobs, such as area and centroid. Calculate Functions based on arithmetic and logical calculations. The library includes operators that perform arithmetic and logical operations on images, vectors and numeric values; 66 operators that equalize images; operators that average images; and operators that produce random or deterministic numbers or number sequences. Calibration 2D calibration functions. Provides means to compensate perspective and lens distortions and convert image coordinates to real world coordinates. Color Color image manipulation. Includes operators that convert between color formats and operators that convert between single and multi-channel images. Comples Support for complex (real and imaginary parts) images. Includes operators that create complex images from real images and operators that extract real components or derived images from complex images. Convert Type Changes in object type and data representation. The library includes operators that cast between numeric types; string management operators; and operators that prepare objects for display. Control Flow control operators in igraphs. Display Operators that pops up a window for either data display or entry. Edges Extraction of edges and contours from images. Includes operators that find point, line or circular edges based on image profiles and operators that extract contours from grayscale or binary images. Filter Convolution filtering of images. Includes general convolution operators as well as optimized special cases of the convolution filters and operators which produce images derived from convolved images. Find Operators that search images for pixel value peaks or pixel patterns. The library includes template matching operators, operators that search for peaks in an image and image to image correlation operators Fit Production of higher level or derived geometric representations from image or geometric data. Includes operators that fit image or geometric data to lines or circles and operators that find centroids, bounding boxes, and convex hulls of image or geometric data. Geometry Spatial transformations of images and other objects. Include operators that perform spatial transformations, such as rotation, shearing, scaling and perspective warping, on images and other objects and operators that perform spatial calibration functions. Measurement Spatial measurement in images or geometric objects. Includes operators that calculate distances and angles between geometric objects; and operators that produce distance maps. Morphology Morphological and other non-linear neighbourhood operations on images. Includes binary and grayscale erosion, dilation and related morphological operators; and median and rank operators. Objects Manipulation of WiT objects and handle elements in vectors and fields in compound objects. Includes operators that create objects; operators that read and write to fields in compound objects; and operators that insert, extract or reorder elements of vectors. 67 Pixel Access Reading and writing pixel values from or to images. Includes operators that set or get pixel values at points, rows, columns, arbitrary lines and rectangular regions of images. Pyramid Multi-resolution image processing. Includes operators that reduce or expand image size; operators that produce multi-scale pyramids from images and operators that reconstruct images from pyramids. Segmentation Binary or labeled images from grayscale source images. Includes thresholding operators and other operators that divide an image into regions based on pixel values. It also includes operators that mark distinctive pixels in the image. Statistics Data reduction by the extraction or calculation of values based on the values in the input image or vector. Includes operators that extract statistics from images or vectors; operators that extract image histograms; operators that extract projections from images; and some additional operators that process the extracted data. Frame Grabber and Hardware The hardware libraries include all operators that are related to hardware. Most of these libraries are frame grabber related, but some, such as TWAIN and DShow, may not be directly related to frame grabbers in the traditional sense. The common aspect of all hardware libraries that is different from other types of libraries is that because they initialize some hardware on startup, you may not be able to run multiple copies of WiT on the same computer if hardware libraries are included in the configuration. Most frame grabbers implement a subset of the operators defined in the Video Acquisition library. Video Acquisition is an abstract library where most of the commonly used frame grabber related operators are defined, but it does not contain any implementation of the operators itself. Because of the diversity of hardware, they are not documented here. You need to consult the operator help for each frame grabber or hardware server from the Operator Explorer in WiT. The Serial IO supports reading from and writing to PC serial ports. SmartSeries SmartSeries is a collection of high-level tools designed to simplify the use of commonly used techniques which are not generally published. SmartSeries are also highly optimized, usually more efficient than code written by application users. SmartSeries libraries are included in a WiT Development License but are purchased separately for WiT run times. SmartSeries Search Fast and accurate pattern search. 68 OCR Character and text recognition. Matrix One and two dimensional bar code reading. Web Continuous web and line scan camera specific functions. 69 70 Data Objects WiT data objects can be images, simple scalar values such as integers or strings, or complex data structures which consist of many different fields. WiT can read, write, display, print, and send data objects across networks, among possibly different computer types. Objects other than images will be referred to as general objects. Objects traveling in an igraph are called tokens. A token consists of a reference to an object plus information about where it is located, how many operators require that object, etc. Viewing Objects You can view objects (images or general objects) produced as a result of executing an operator, or view object files (saved as WiT objects) directly. Viewing Objects in Graph Mode There are two ways to display an object token when running in graph mode: you can send the token to the display operator, or you can put a probe (magnifying glass) on a link. Display pops up a window whenever it receives a token. If the object is an image, it will be displayed in its original size if it is smaller than the size of the display screen. If it is bigger, the window is limited to the size of the screen, and scroll bars appear automatically to let you pan the image within its window. If the object is a general object, it is displayed as formatted text. If a probe is put on a link, then whatever travels on that link when the igraph is running will be displayed in a pop-up window, exactly like the display operator. Viewing Objects in Script Mode In script mode, objects produced by operators are automatically shown in thumbnail form on the workspace. If you want to see them at their original scale, double click the left mouse button at the cell you wish to see, and the object will come up as a pop-up window. Viewing Object Files Select File/View objects... from the menu bar. This brings up the familiar file dialog. WiT objects have a 'wit' extension. Select a file and click the OK button. The object appears in a detached window. 71 Studying Images WiT provides many utilities for examining image data: • • • • • • • Report image type: unsigned 8-bit, floating-point, color, etc. Report image width and height. Report mouse position in image coordinates. Report pixel values at and around mouse position. Draw X and Y profiles at mouse position. Change image color map, including user-defined color maps. Adjust image contrast. These functions are accessed from the image property panel. To bring up the property panel for an image: 1. 2. 3. Move the mouse cursor inside an image which has been displayed in its own window (i.e. not in miniature form on a card in Script Mode). Press and hold the right mouse button. A menu pops up. Select the Properties... menu item. The image property panel pops up: Adjusting Image Colors Sometimes you may want to adjust the contrast on a grayscale image to study how the pixel values are varying. Or you may wish to install a pseudo-color colormap to further bring out pixel variations. 72 Studying Pixel Values To study the exact value of a pixel or an area of pixels in an image, perform one of the following list of steps: 1. 2. Move the mouse at the location where you want to see the pixel value and leave the mouse there. After a few seconds, a tool tip comes up which displays the pixel value and the exact location of the pixel. Or: 1. 2. 3. Bring up the image property panel. Check the Magnifier box for the Inspect item. A magnifier window comes up. Move the mouse inside the image. Drag with the left mouse down. By default, a 3x3 area is displayed centered on the pixel the mouse is pointing. The values displayed on the magnifier window depend on the image type. For example, if the image is floating-point, then the values are floating-point numbers. If the image is color, then the values are RGB triplets. Notice the small rectangle displayed on the image. This is the area which is being magnified. You can change the size of the magnifier window. 73 Plotting Pixel Profiles To plot the pixel value variation along the X or Y axis on the image: 1. 2. 3. Bring up the image property panel. Check the X or Y check box for the Inspect item. A pop-up window comes up which plots pixel values along the X or Y axis. Move the mouse inside the image. Drag with the left mouse down. The profile plot is updated as you drag your mouse. Notice also the line on the image. This is the line of pixels which is being plotted. Pixel Profile Plot To remove a profile window, do one of the following: • • • Uncheck the appropriate Inspect check box. Close the profile window. Close the image window: profile windows are destroyed automatically when the parent image window is destroyed. Group Control of Images From the image property panel, you can manipulate a group of images with a single action, such as changing the window size, the contrast, turning on or off profile windows, and changing colormap. 74 You can also make the inspect position on a group of images track changes to the inspect position in one image. To control a group of displayed images: 1. 2. Bring up the image property panel. For the Apply to item, choose All if you want to control all currently displayed images, Selected for only the selected images, and Except selected for only the non-selected images. All subsequent actions on the image property panel subsequently affects the chosen group of images. Resizing Images When images are first displayed, they are displayed in their original size. You can change the size of the image by changing the size of the window. WiT handles all window size changes in a consistent way. You can also scale an image precisely using its property panel. Setting an Exact Pixel Scale To set an exact pixel scale: 1. 2. 3. 4. Bring up the image property panel. Click the button for the Pixel scale item. A pixel scale panel comes up. Enter desired scales in X and Y. A larger scale means a pixel will appear larger. Click . The image is redisplayed with the new scale. If the image has not been previously zoomed (not displayed with scroll bars), then the image window is also resized to fit the new image. If the image has been previously zoomed, the image window size will not change, but the image shown in the window will change. 75 Setting an Exact Image Frame Size To set an exact image frame size: 1. 2. 3. 4. 5. 6. 7. Bring up the image property panel. Click the button for the Frame size item. A frame size panel comes up. Enter desired sizes in X and Y. Click . The image is redisplayed with the new frame size. If the new frame size is larger than the image, and the image has not been previously zoomed (displayed without scroll bars), the pixel scale is increased so that the image will fit the new frame. If the new frame size is larger than the image, and the image has been previously zoomed (displayed with one or both scroll bars), the frame size is limited to the size of the image. If the new frame size is smaller than the image, scroll bars will appear. Zooming and Panning Images Sometimes you want to magnify an image without increasing the window size (i.e., make the window size smaller than the image size), so that the window displays only a portion of the image. You may then want to pan the window to look at different portions of the image. You can specify an exact magnification scale with the Pixel scale control on the image property panel, or you can use standard interactive zoom techniques for approximate scales. 76 Image Types WiT supports many different image types. Samples of all supported image types are provided in the $WITHOME\images directory: Image Type Example Image 8-bit unsigned sample 8-bit signed mri 16-bit unsigned fighter 16-bit signed brain 32-bit grayscale floating-point moon 24-bit color frog 64-bit complex fft Most standard WiT operators can deal with all appropriate image types. For example, conv2d can handle all image types except complex. Printing Data Objects Printing Images There are two ways you can print images from WiT directly: • • Display the image and select the File/Print menu item. Execute the print operator with the image as input. One useful technique is copy an image to the Windows clipboard (using the Print Scrn key on the keyboard with or without the ALT key held down) and paste it to another application which can print it. This can be useful if you have a good photo touch-up program. Printing a General Data Object There are two ways you can print general data objects from WiT: • Display the object and select the File/Print menu item. The object is printed as it appears on the screen. 77 • Execute the print operator with the object as input. This method has the additional option of printing the object out as text, so that the entire object can be printed and the output can span multiple pages. See the print operator on-line help for details. Object Window Placement In a WiT session, it is possible that many object windows are displayed simultaneously. There are three methods that WiT can use to position new object windows on the screen, controlled with the Object placement widget of the Advanced Options panel: • • • Tile windows Place windows at where the mouse is Place windows randomly on the screen Once a data object has been displayed in a window, you can move the window around or resize it. You can also rearrange or close multiple object windows using the Windows menu. Reading and Writing Object Files When WiT reads an object with operators such as rdObj or rdImage, and the file name specified is not an absolute path name, WiT uses a search path to look for it. Search paths allow frequently used objects to be found regardless of where your working directory is, and without you having to specify the complete path. Search paths are set up in the configuration file. They can also be changed interactively with the WiT Manager. Writing objects (operators such as wrObj or wrImage) is handled differently. If the file name is not absolute, the object is written to the current directory. 78 Frame Grabbers WiT uses a high-level set of operators to make usage of different frame grabbers more uniform and easier. Once a frame grabber has been setup, you can acquire frames with the acquire operator, regardless of what frame grabber you are using. In this section we discuss the general procedures for setting up a frame grabber, as well as some of the more advanced operators that are commonly used. We will also discuss the use of the Frame Grabber Tool to configure frame grabbers, and the emulator for testing igraphs without an actual frame grabber. Setup In order to provide WiT users with a uniform operator interface to all frame grabbers, WiT adds a support layer between the frame grabber driver software and WiT itself. For historical reasons, this layer is referred to as a server, although it is simply a library, much like an ordinary operator library in WiT. At installation time, you must make sure to check the WiT support for the frame grabber(s) that you will be using. This installs only the WiT servers. You must also install the frame grabber drivers separately, using the installation software provided by the manufacturer of the frame grabber. The WiT CD includes drivers for all frame grabbers supported by WiT. But you have to install the drivers manually. Most frame grabbers have test or demo programs that come with the driver. It is strongly recommended that you run those programs at least once after driver installation to make sure the frame grabber is properly installed. WiT adds a program icon to the ‘start’ group in the WiT program group for each frame grabber installed. If you start WiT by clicking the appropriate icon, WiT will start with the frame grabber properly loaded. You can also configure which frame grabber or frame grabbers for WiT to use by using the WiT Manager. See ‘Configuration/Library and Server Configuration’ for details. Common Operators In addition to the acquire operator, there are several operators which are often useful when using frame grabbers. Not all frame grabbers support all WiT video acquisition operators. The acqStart and acqStop operators instruct WiT to do image acquisition continuously. This usually results in faster frame rates since the acquisition can be performed in parallel with other computations. The drawback of doing this is that the PCI bus and memory access will be busier. If intensive computation is required and the frame rate does not need to be high, then these operators should not be used. 79 The acqLive operator pops up a live video window when it is executed. This can be very useful when interactive aiming or focusing is necessary as an algorithm is executed. The acqOverlay operator creates overlay graphics that are displayed with acqLive. It works much faster than displaying an image with graphics continuously using the overlayData operator. The frames parameter of acquire itself can be quite useful when high-speed acquisition is required, where a burst of frames need to be acquired as fast as possible. Frame Grabber Tool The Frame Grabber Tool in WiT is useful for testing quickly whether a frame grabber has been properly setup, and to adjust parameters and settings. It can display live video, snap individual frames, and acquire continuously. The difference between live and continuous is that in live mode, images are displayed as fast as possible. But it may use a different mechanism than the one used by the acquire operator. For example, data may not be transferred to host memory at all when in live mode. In contrast, continuous mode works by simple calling the acquire continuously. The Frame Grabber Tool can be run as a separate program outside of WiT. This is useful when you need to setup and test a frame grabber on a run time PC which does not have WiT installed. The Frame Grabber Tool does not require a WiT license and it is much smaller and therefore can start up much faster. It shares the same saved frame grabber settings as WiT. See section ‘User/Parts and Tools List/Frame Grabber Window’ in the Reference Manual for details. The standalone Frame Grabber Tool does not use WiT configurations. To choose a frame grabber, you must provide the name of the server (DLL) as a command line option. E.g.: witfg -fg wbandit 80 Multiple frame grabbers can be loaded so that you can choose the source from inside the Frame Grabber Tool. E.g.: witfg -fg wPC2Vision -fg wVDig You can reset the saved frame grabber settings to their default values by specifying the ‘safe’ option. E.g.: witfg -safe -fg wPC2Vision Emulator Sometimes it is convenient to test an igraph without using an actual frame grabber and camera. Perhaps you are editing an igraph on a notebook PC, or perhaps you want to test your igraph with a fixed set of images. The frame grabber emulator server, emu, is provided for such purposes. It can emulate a frame grabber by simply providing a series of generated moving images, or it can use saved image files. Image files can be specified from the Advanced Panel in the Frame Grabber Tool. Use a wild card character to load a list of files. E.g.: im*.wit 81 82 Usage Techniques Every effort has been made to make WiT a user-friendly program. Consequently, many common operations, such as zooming and panning, or choosing a font, which are needed in different situations, are done in a similar way. Sometimes such shared techniques involve some combinations of the mouse and/or keyboard. For example, to magnify a portion of a window, whether the window is the workspace, an image, or a 3-D plot, the same combination of mouse button and motion is used. In other cases, a special panel (window) is used. For example, when selecting a color for the background of the workspace, or a color for an image colormap, the same Color panel is used. This chapter discusses those techniques that do not present itself as a window. Those are discussed in chapter Parts and Tools List. Graphic Objects Graphic objects in WiT form a general class of visible objects. They can be selected, moved, copied, and pasted using the same techniques. WiT uses three types of graphic objects: • • • Operator icons on an igraph Links on an igraph Annotation objects (circles, lines, text, etc.) on an igraph or overlaid on images Selecting Graphic Objects To select or deselect one graphic object: 1. 2. 3. 4. 5. Clicking (press and then release) the left mouse button while pointing at the object. The object turns red when it is selected (stippled on a monochrome). If you selected the wrong object by mistake, selecting another object will cause the previous one to be deselected. If you want to add an object to the selected list, click the left mouse button with the CTRL key held down. If you want to deselect an object from the selected list, click the middle mouse button on the already selected object. Clicking the left mouse button at a blank area deselects all objects. 83 To select all objects within an area: 1. 2. 3. Move the cursor to some blank spot, then press and hold the left mouse button. Drag your mouse. A rubber band rectangle is drawn with one corner pinned to the position where you first clicked the mouse. The other corner is tied to the mouse position. Drag the mouse until all objects you want to select are completely within the rubber band rectangle, then release the mouse button. Deselecting Graphic Objects To deselect all currently selected objects, click the left mouse button at a position where there are no 2D objects. To deselect one of the currently selected objects, click the left mouse button at the object with the CTRL key held down. Moving Graphic Objects To move one object: 1. 2. 3. 4. Select the object you want to move. Press and hold the left mouse at the selected object. Start dragging your mouse. The object moves along with the mouse. The cursor changes to a truck to indicate you are moving objects. Drag the mouse until the object is at the place where you want it, then release the mouse button. To move multiple objects: 1. 2. 3. 4. Select all the objects you want to move. Press and hold the left mouse at any of the selected objects. Start dragging your mouse. All the selected objects move along with the mouse. The cursor changes to a truck to indicate you are moving objects. Drag the mouse until the objects are at the place where you want them, then release the mouse button. Deleting Graphic Objects To delete selected graphic objects, do one of the following: 1. 2. 3. 4. 84 Click the button. Select Cut from the Edit menu. Select Cut from the pop-up menu. Type CTRL-X. Copying Graphic Objects To make a copy of the selected graphic objects, do one of the following: 1. 2. 3. 4. Click the button. Select Copy from the Edit menu. Select Copy from the pop-up menu. Type CTRL-C. Pasting Graphic Objects To paste graphic objects that have been copied or deleted, do one of the following: • • • • Click the button. Select Paste from the Edit menu. Select Paste from the pop-up menu. Type CTRL-V. Undo the Last Edit Action To undo the last annotation edit action, such as cut, copy, move, or paste, do one of the following: • • • • Click the button. Select Undo from the Edit menu. Select Undo from the pop-up menu. Type CTRL-Z. Editing Graphic Objects Some objects, such as igraph links and polygon graphic objects, can be edited (moving the link corners or polygon vertices). Others, such as igraph operators, are fixed in both size and shape and cannot be modified. Where applicable, to adjust an object: 1. 2. 3. 4. Make sure the object you want to adjust is not selected. Press and hold the left mouse button at the feature (link corner, polygon vertex, etc.) which you want to modify. Start dragging your mouse. The cursor changes to a screw driver, and the feature rubber bands to the position of your mouse. When the feature is at the position you want it to be, release the mouse button. 85 Properties of Graphic Objects All graphic objects have properties which can be edited for each individual object by clicking the right mouse button at the object. Different object types: operators, links, and annotations, have different properties. Annotation Objects Annotation objects, e.g. rectangles, circles, and text, are used on igraphs for documentation and also used by operators such as getData, iMeas, and extract to manipulate images. Sometimes they are for display only, and sometimes you can edit them. Whatever the application, you interact with annotation objects directly on the window where the annotation objects are via the mouse and keyboard, and also with the Graphics Editor panel. Creating Annotation Objects Select the type of annotation object you want to enter by pressing a button on the second row of buttons on the Graphics Editor. When an annotation object is added to an igraph, the Graphics Editor automatically switches back to Select mode after the object is defined. This reflects the common sequence of adding a graphic then moving or resizing its position. When annotation objects are entered on images (e.g. using getData), the Editor remains in data entry mode after an object is added. This behavior is more convenient in this situation because usually the user needs to enter a more than one graphic. Because each graphic type is so different from the others, the input procedures for each are necessarily different. Following is a description of how each graphic object type is entered. The Graphics Editor also reminds you of what you should do next in its status area: Point Each click defines a point. Line Press and hold left mouse button to define first end of line, then drag to other end of line and release button. Text Click at where you want text to begin. You will see a vertical bar (the text cursor) appear. Enter text string from keyboard. Click left mouse button or hit escape key to terminate text entry. Rectangle Press and hold left mouse button to define first corner, then drag to second corner and release button. Circle Press and hold left mouse button to define center of circle, then drag to desired size and release button. Polyline Click (press and release) left mouse button to define first point. Each subsequent click defines a corner. Terminate with double-click. Click middle mouse button or backspace 86 key to undo the last point. Polygon Same as polyline, except that when you terminate, the polygon is closed automatically. Click middle mouse button or backspace key to undo the last point. Annotation Object Properties Each annotation object has a number of properties which are user selectable. All objects have a pen (outline) property. Rectangles, circles, and polygons also have a fill property. Text objects have a font property. Changes made to properties are global within an editing session, but independent among different sessions. For example, if you are entering graphic data on multiple images, and you change the pen color to blue on one of the images, all subsequently created objects in that image will have a blue outline. But objects entered in other images will not be affected by this color choice. To edit the properties of annotation objects, do one of the following: • • • To edit the properties of one object, click the right mouse button at the object. The graphic property panel for the object appears. Change property settings and then click the button. To edit the properties of more than one object, select the objects you want to change. Then from the Graphics Editor. select one of To change the properties of future objects only, deselect all objects. Then select one of from the Graphics Editor. Pen Color of Annotation Objects The pen color is used to draw text, points, lines, and polylines, and to draw the outlines of rectangles, circles, and polygons. You can choose any color for the pen. For rectangles, circles, and polygons, you can disable the outlines by disabling the pen color. To change pen color of graphic objects: 1. 2. 3. For one object click the button on the graphic property panel. For selected or future objects, click the button on the Graphics Editor. The Pen Panel comes up. Click the button. The Color Panel comes up. Choose the color you want. To disable outlines for rectangles, circles, or polygons: 1. 2. For one object click the button on the graphic property panel. For selected or future objects, click the button on the Graphics Editor. The Pen panel comes up. Click the button. 87 Fill Color of Annotation Objects For rectangles, circles, and polygons, you can choose to fill with any solid color, or have them appear hollow. To change fill color of a circle, rectangle or polygon: 1. 2. 3. For one object click the button on the graphic property panel. For selected or future objects, click the button on the Graphics Editor. The Fill panel comes up. Click the button. The Color panel comes up. Choose the color you want. To make a circle, rectangle or polygon hollow: 1. 2. For one object click the button on the graphic property panel. For selected or future objects, click the button on the Graphics Editor. The Fill panel comes up. Click the button. Changing Annotation Text Annotation text can only be changed on the property panel (section 'Graphic Object Property Panel', chapter 'Parts and Tools'). Annotation Object Fonts To change the font of text graphic objects: 1. 2. For one object click the button on the graphic property panel. For selected or future objects, click the button on the Graphics Editor. The Font panel comes up. Select a font and click the OK button on the Font panel. Selecting Windows The notion of selected windows is useful when printing, and when the object type supports the application of properties to a number of windows. Displayed image windows is one example. To select a window: 1. 2. 88 Press and hold right mouse button inside window to bring up a pop-up menu. Choose the Select (always the first) item. A check mark at the upper left corner of the window indicates it is selected. To deselect a window: 1. 2. Press and hold right mouse button inside window to bring up a pop-up menu. Choose the Deselect (always the first) item. The check mark disappears, indicating the window is not selected. Resizing Windows For windows which support scroll bars, if the entire object is visible (i.e. neither the horizontal or vertical scroll bars showing), and you resize the window, then the object is scaled to fit the new window size, as illustrated below: Sizing an Image without Scroll Bars When only part of the object is visible within a window (i.e. one or both scroll bars showing), then resizing the window will not scale the object, instead, the new window becomes the new visible area, as illustrated below: Sizing an Image with Scroll Bars If a window with scroll bars is enlarged to be bigger than the object itself, the scroll bars will disappear, and the object will scale to fit the new window size. Windows which display general objects do not scale the text inside when the frame size is changed. If a different font size is desired, use the pop-up menu. 89 Zooming and Scroll Bars Most windows in WiT can be zoomed and panned. For example, you may find the default icon sizes too large when designing a large igraph, so zooming out (making the icons smaller) is more convenient. Or when you are examining images, you may want to study the image on a larger scale, but you do not want to make the window bigger, which may take up too much room on your screen. Zooming changes the scale of whatever the window contains without changing the window size. WiT provides you with a consistent and convenient way to do zooming and panning on all windows where such actions are appropriate. Zooming To activate zooming, press and hold down the right mouse button to bring up the property panel of the window you are going to zoom, and select the Zoom... menu item. The cursor changes to a magnifying glass. When you move your mouse to the right of the position that you initiated the zoom, the mouse cursor changes to (a magnifying glass with a '+' sign). If you move to the left, the cursor will (magnifying glass with a '–' sign). The '+' sign indicates that if you release your mouse change to button now, objects will appear larger (zoom in), The '–' sign means the opposite (objects smaller, zoom out). When zooming in, the area within the rubber band rectangle will be magnified to take up the entire window. When zooming out, the entire window will be shrunk to fit into the rubber band rectangle. Restoring to Original Scale and Position After Zooming Windows which support zooming have a View all item on their property menu. Choosing this item will cause the window contents to be scaled such that all objects are visible. For example, when viewing an image, the image will be scaled so that it exactly fills the window. The Normal size item (if it exists) in a property menu will restore all objects at original scale. Scroll Bars In windows that support zooming, scroll bars appear automatically whenever the object cannot be displayed completely within the window, and they disappear whenever the entire object is visible. The horizontal and vertical scroll bars on a window are independent. For example, if all of the width of an image is visible, but the height of the window is less than the height of the image, then a vertical scroll bar will be visible, but no horizontal scroll bar will be shown. 90 Printing Most graphics windows in WiT can be printed either directly to a printer or to a file. You can also print a WiT image or general object directly using the print operator. To print some windows, select the File/Print... menu item to bring up the Print Panel. Most graphics windows in WiT can be selected for printing. If you bring up the property menu in a graphics window, you should see that the first item is Select. Choosing this item will cause a check mark to be displayed on the upper left corner of the window. When Windows to print is set to Selected on the Print panel, only frames with the check marks will be printed. Normally, when you click the button, the print job will be initiated quietly. However, the first time you print something, WiT will bring up the printer setup dialog so that you can set up options such as paper orientation, which printer to use, etc. If you wish to change printer configuration after the first print job, you can bring up the setup dialog again with the File/Print Setup... menu item. 91 92 Script Mode Although igraphs are powerful and easy to use, there are times when you just want to apply one or two operators to some data objects. For example, you may want to read an image and transpose it, then save it back. Having to build a tiny igraph and then run it is inconvenient. Especially when you know you will never use the igraph again. So WiT provides a script mode of execution. In this mode, operators that you select are executed and the results shown immediately. Script mode is useful in exploring and understanding the rich set of imaging operations WiT offers, as well as debugging any new operators that you have developed yourself. The menu bar and tool bar remains the same in script mode, although some items may be disabled. The workspace is used to display thumbnails (cells) of data objects: WiT in Script Mode To run WiT in script mode, do one of the following: • • • Use the command line option -mode script. Click the tool bar button. Bring up the Options panel. Choose Script for Mode. Script Cells Displaying the Contents of a Script Cell Data objects are shown as a thumbnail in each cell. Images are scaled down to fit the cell. Text objects may be truncated. To display the data object at full size, double click the left mouse button at the cell 93 you want to display. The object is displayed in a pop-up window in its original size. The label on the pop-up window is the same as the name of the cell. Selecting Script Cells Single cell Click left mouse button at the cell Add a cell to the current selection Click middle mouse button at the cell Remove a cell from the current selection Click middle mouse button at the cell Select all cells Do one of the following: • • Deselect all cells Select Edit/Select all menu item from menu bar Select Select all from workspace menu Click left mouse button at an empty location Deleting Script Cells To delete a cell, you need to select it first. Then do one of the following: • • • • Click the button. Select Edit/Cut menu item. Select Cut from the workspace menu. Type CTRL-X Renaming a Script Cell To change the name of a cell, point the mouse at the cell and press and hold the right mouse button. Select rename from the pop-up menu. Then type in the new name in the pop-up dialog. Renaming a Script Cell 94 Sequencer and Collector in Script Mode With the exception of sequencer and collector, all data-flow operators are not applicable in script mode. Sequencer executes like any other operator in script. It needs a vector object as input and each element of the vector is expanded to an individual cell in the workspace. The name of the outputs is the name of the output with a number appended to it, e.g. myData-1, myData-2, etc. Collector behaves significantly differently than in igraph mode. It also differs from other operators. In script mode, collector only requires one data input, the flag input is not applicable. The cell name for this input may be a list of names, separated by white space. Each of these names may contain wild card characters. If any of these names contain spaces or separator ( characters, it must be quoted. Some examples: obj1 obj2 obj3 obj4 data[1-9] myImages* obj1 sa*s "first image" another "what??" "say \"thank you\"" To add a cell to the input, either type it in or point the mouse at the cell to add and click the middle mouse button. Script Files Every operation you perform in script mode is automatically logged. A script can be saved to a file, read back, and re-executed. Script files are saved with a 'wsc' (which stands for WiT Script) extension. Running a Script To run the currently loaded script file, do one of the following: • • • buttons. These buttons all start the history running, but with Click any one of the different speeds. Select the Run/Start menu item. Press the F5 function key. Speed selection only affects the delay between each step when a script is replayed. Speed selection does not affect manual execution. 95 Saving a Script To save the current set of script actions, select the File/Save menu item. To save the current set of script actions to a different file, do one of the following: • • Click the button. Select the File/Save as... menu item. When you save an existing script to itself, WiT will do it quietly. If the script is new, selecting File/Save has the same effect as selecting File/Save as.... When saving a script to a different name, a file dialog comes up for you to select a file name. WiT adds the 'wsc' extension automatically to the name you enter, so you do not have to type that yourself. If you try to save a script as another file name and that file already exists, WiT will ask for your confirmation to overwrite the previous file. Reading a Script File To read a previously created script file, do one of the following: • • Click the button. Select the File/Open menu item. A file dialog comes up for you to select a script file. Script files have a 'wsc' extension. The initial directory comes from the system registry or from the command line. Afterwards, the directory is the one where the last script file is loaded from or saved to. Erasing the Current Script To erase the current script, do one of the following: • • • Click the button. Select File/New. Select all the text in the script window, then delete the selection. Editing a Script File Currently there is little support for editing a script file, since script mode is intended for short sequences of operators to test out simple ideas, not long complex programs. You can edit them directly in WiT by choosing the Edit/Script... menu item. 96 Script files are text files, so you can use a text editor to edit them. See Appendix Script File Format for a description of the file format. 97 98 Network WiT is a powerful tool when run on a single computer. However, there are even more options available to the WiT user in a networked environment with multiple computers. You can configure WiT to use a floating license. This way many users can share the same WiT license on the network, provided that total number of users at any one time does not exceed the number of WiT licenses available. You can also configure WiT to spread out computation and data acquisition to multiple computers, thereby either reducing overall execution time or allowing coordinated execution among several computers. The WiTRAS (RAS stands for Remote Access Server) program is the agent that allows these network features to run with minimal user effort. eWiT is a program that attaches to a main WiT program for parallel networked execution or remote data acquisition. WiTRAS - Remote Access Server The WiTRAS (Remote Access Server) program is required when remote connections on a network are launched by WiT or when a floating license manager is desired. This section describes the function of WiTRAS for managing remote connections. In this case, WiTRAS is started and left running as an idle process in the background ready for connection to WiT to launch a connection to either another eWiT. This is done by putting the icon in the Startup Folder of any machine which may start eWiT. On NT systems, the WiTRAS program can be made into a service so it continues to run even though a user logs out from their session. This is done using the svrany.exe program found in the NT resource kit which is installed from the NT CD-ROM. You can also start WiTRAS by selecting the the WiT program group. icon from An Idle WiTRAS The WiTRAS program runs in an idle state awaiting a connection from WiT to start up a program, usually eWiT. Upon successful connection to WiTRAS from WiT, the program name and arguments are sent to WiTRAS so the executable can be located. Once the program starts, WiT will connect to it and utilize its resources in the execution of an igraph. When a program is started by WiTRAS, its process identifier is stored in an internal table along with the user and machine name originating the request. When a start up request occurs again for the same user and machine name, the process identifier is looked up from the table. If the process identifier is 99 still active, then the process is shutdown and restarted. Normally, programs will shutdown when WiT exits and so the process identifier is not found and no shutdown is required by WiTRAS. Sometimes, however, a server may encounter a fatal error or hang in which case the shutdown by WiTRAS ensures smooth reconnections. Installing TCP/IP WiTRAS and remote connections based on a network use the TCP/IP (Internet) protocol to communicate with each other. If you are running on either Windows 9x or NT, the TCP/IP protocol can be easily installed using the Network icon in the Control panel. The procedure is summarized below for Windows 9x: 1. 2. 3. 4. 5. 6. 7. 8. 9. Open the Control panel and select the Network icon. Check if the TCP/IP protocol is installed. If it is, then you are done, otherwise click Add. Click Protocol, and then click Add. Click Microsoft, and then click TCP/IP. Click OK. Click on your network adaptor then click Properties. On the IP Address tab, click 'Specify an IP Address' and then type your IP address and subnet mask. An IP address is a 4 digit number (each digit separated by dots) and must be unique if you are connected to an existing network. Consult your network administrator for help. If you are managing your own network, a valid IP address is any combination of digits with the following general exceptions: 1. The address cannot end with a zero, e.g. 134.87.102.0 2. The address should not use a loop back address of 127.0.0.1 When TCP/IP is configured, select OK and close down the Network dialog. You will be told to reboot your computer. Use the utilities called FTP or TELNET to test your network. For example, start a DOS prompt shell and type: ftp 134.87.102.1. After everything looks OK, start up the WiTRAS (Remote Access Server) by launching the icon on the machine which you intend to use with WiT for running igraphs. You must also start WiTRAS on the machine you are using WiT. In general, WiTRAS must run on any machine where either WiT or a WiT connection is run. Note that the IP address of the machine is reported in the title bar of the WiTRAS application. eWiT In addition to multi-threaded parallel processing on dual processor motherboards, WiT supports parallel execution on distributed computers over a TCP/IP network or over the PCI bus communicating to many Coreco Mamba boards using a product called eWiT (for Embedded WiT). eWiT is a program that supports most of the capabilities of WiT, with the exception of the graphical user interface. It communicates with WiT using TCP/IP when connected via a network, or a special communication channel specific to the hardware resource. For example, when eWiT is run on the Coreco Mamba board, WiT communicates with eWiT via the PCI bus. eWiT listens to the WiT master for operators and subgraphs to execute. Because it has most of the capabilities of WiT, eWiT can be configured 100 (using the WiT Manager) to support all kinds of frame grabbers and hardware, and provide those services to WiT for execution in an igraph. WiT coordinates all the local CPUs and eWiT connections so that many operators in an igraph can be executed at the same time. You can make as many eWiT connections to WiT as you want. There are various reasons for using eWiT. If your computer is connected to a local area network, you may want to run eWiT on all machines that are not busy, so that your igraphs can execute faster. Bear in mind though that usually communication speed is much slower compared to execution speed. So that, in general, you want to distribute operators or subgraphs to eWiT only if the operator or subgraph takes a long time to execute. In the case of eWiT and Mamba boards, the communication mechanism is based on the PCI bus and is very fast thereby providing a number of processors with little data transfer and synchronization overhead. eWiT can run entire subgraphs in a single message from the master WiT running on the host reporting to the host only when results are completed. Another common reason for using eWiT is for grabbing images through networked computers where the frame grabber is on one computer but the igraph and developer are on another computer elsewhere. There are two execution modes in eWiT, dumb and smart. Dumb eWiT can be executed on any PC, without the need of a license. Smart eWiT can only be run on PCs which has an eWiT license. Dumb eWiT can only execute primitive operators which are non-interactive. Smart eWiT can execute subgraphs and interactive operators in addition to all other primitive operators. Because executing an operator on eWiT requires some communication overhead, smart eWiT is much more efficient when an algorithm can be partitioned at the subgraph level. Subgraphs are sent from the host WiT to all connected eWiTs only once, just before an igraph is executed. After that, only a command and object data need to be transmitted to eWiT during igraph execution. If you run eWiT on a PC with an eWiT license, eWiT will automatically start up in smart mode. eWiT on Start Up The eWiT window consists of a toolbar and a status window. The status window reports similar messages that the WiT status window reports. The toolbar has speed buttons that allow you to control how much information is reported in the status window. gives you the most information and gives you none, for fastest execution speed. The clears the status window. 101 eWiT on startup When eWiT starts, it uses the WiT configuration file specified the connection request and loads all the necessary libraries and hardware support. It then attempts to connect to a master WiT process by using the supplied communication address, which currently is either an IP address or Mamba address. Normally eWiT is started automatically when WiT loads a configuration that includes any remote connections. WiT starts up in master mode, which enables it to listen for eWiT connection requests. Then, for each eWiT specified in the configuration, WiT launches a copy of eWiT at the address specified. For IP addresses, WiT launches eWiT by sending a command to WiTRAS on the computer with the specified IP address. WiTRAS then starts eWiT on the destination computer, giving eWiT the IP address of the computer which is running the master WiT process. When eWiT starts, it requests a connection to the master WiT process. For Mamba embedded processors, WiT launches eWiT using the Sapera server based on the Mamba address specified in the WiT configuration file. eWiT can run in either licensed or unlicensed modes. In unlicensed mode, you can run eWiT without purchasing an eWiT license so that you can see the benefits of the product by testing out how eWiT can distribute your igraph processing. With eWiT in unlicensed mode, you can only schedule individual operators on eWiT from your igraph where each operator requires a communication message thereby creating delays due to message passing. In licensed mode, however, you can schedule entire subgraphs which allow a large piece of work to be scheduled remotely in a single communication message where you will achieve the fastest execution time possible. Assigning Subgraphs If you want to experiment using eWiT, start WiTRAS on your computer and run WiT with the configuration eWiT.wrc. This will start an eWiT connection on the same computer as the WiT master. After WiT comes upcreate a subgraph. Notice that the property panel of all subgraphs now has a Server item: 102 To study the interaction between WiT and eWiT, press the button on the eWiT toolbar. This will cause more diagnostic messages to be displayed in the eWiT window while your algorithm executes. Next click the button on WiT to start running the igraph in turtle mode. You should see messages showing you what is executed on WiT and what is executed on eWiT, as well as information about what data objects are transmitted between them. Adding a Remote Connection 1. Select the Edit/Connections... menu item from the WiT Manager. The Connection Editor panel comes up. Select the Connection Editor 2. 3. 4. 5. 6. 7. 8. Select the Connection/New menu item. The New Connection panel comes up. Enter a name for eWiT in the label field. Set Program to eWiT. Set device to Network. Enter IP address of the PC that will run eWiT in the IP Address field. e.g. 123.080.221.1 Set the configuration file for eWiT in the Options field, e.g. ‘-config default.wrc’ (do not enter the quotes). Close the Connection Editor. 103 9. Save your configuration file (File/Save as). Added an eWiT Connection Removing a Connection 1. 2. 3. Select the Edit/Connections... menu item from the WiT Manager. The Connection Editor panel comes up. Under the Name column, click to select the connection you want to remove. Select the Connection/Remove menu item. Editing Settings of a Connection 1. 2. 3. 4. 5. 6. 104 Select the Edit/Connections... menu item from the WiT Manager. The Connection Editor panel comes up. Under the Name column, click to select the connection you want to edit. Select the Connection/Edit menu item. The Edit Connection panel comes up. Change the Label, Program (eWiT or WiT), Device (Network or specific Mamba card), IP address, and/or the start-up Options. Close the Connection Editor. Save your changes (File/Save). Configuration The WiT work environment is user-configurable. Configurable options include the position and size of the main WiT window, where pop-up windows are placed, where servers, libraries, or icons are located on the file system, how many servers to run, customized operator icons, etc. When WiT starts, options such as the position and size of the main workspace are set with the following sequence (increasing priority): 1. 2. 3. Built-in default options. Options stored in the system registry. Override any default options. Options specified on the command line. Override any registry options. Library and Server Configurations You can select which operator libraries and hardware (frame grabber) servers to use with WiT. Library and server configurations are done using the WiT Manager, which is documented in more detail in the Programmer’s Manual, since most of the tools in the WiT Manager are for creating and managing custom operators. If you do not plan to add C/C++ operators to WiT, then most likely all you ever want to do with the WiT Manager is to select an existing configuration as the default. To do that, start the WiT Manager from the WiT program group. Click the button, and select the configuration you want. Then select the ‘Tools/Activate’ menu item. The configuration will be used the next time you start WiT using the main WiT icon. 105 To add a library to a configuration, select a library on the left window (the Available list), then click the button to add the library to the Installed list. To remove a library from the installed list, select it and click the button. When you change a configuration that comes with WiT, you should not want save the new configuration to the original, since you may want to revert to the original configuration in case something goes wrong. Instead, select the File/Save as menu item. User Preference Options Following is a list of all the GUI configuration options and their meanings. Each option has a default value in WiT. Options can be retrieved from the system registry, or can be specified as a command line option. Default values are used the first time you run WiT or when you use the safe option. Option Description autoClr Specifies whether pop-up object windows should be cleared 1 automatically when an igraph or demand history is run, or when a new igraph or demand history file is loaded. Valid values: 0 (off), 1 (on). autoRun Specifies whether an igraph or a demand history file should be run automatically when it is loaded. Valid values: 0 (off), 1 (on). 0 bell Turns audible bell on or off. Valid values: 0 (off), 1 config Specifies the name of a WiT configuration file (‘.wrc’) to use at startup. default.wrc demo Run WiT in demo mode. N.A. igShowObjNames Control how igraph operator and link names are displayed. Valid values: instance (show base name with instance number, e.g. fft #3), base (show only the base name, i.e. without the # number), none (do not show any name). Default Value instance grid Grid size (in pixels). Valid values: 0 — 100. 10 launchSvr If enabled, servers specified in the configuration file are automatically launched. Regardless of the setting, WiT will try to connect to the specified servers. So if you do not check this box, you must launch the servers by hand. This allows you to start a server using a debugger. Valid values: 0 (disable), 1 (enable). 1 logStatus Log status windows messages in a file. Valid values: any valid file name. None 106 master Enables WiT to listen for eWiT connection requests. N.A. maxThreads Number of execution threads that WiT uses. Valid values: 0 means use the same number as the number of system processors. A value of 1 or more fixes the number of threads. 0 mode WiT execution mode. Valid values: graph, script. graph open Load igraph or demand history file on startup, depending on the execution mode. Valid values: any valid file name. None pick Pick tolerance when editing igraphs. Valid values: 0 — 10 5 place Object window placement strategy. Valid values: mouse (window tile upper left corner goes to where the mouse is), tile (windows are tiled across screen), and random. position Position and size of the main WiT window. Four integers: upper -1 -1 600 300 left X, upper left Y, lower right X, lower right Y. If upper left X is -1, window is centered horizontally. If upper left Y is -1, window is centered vertically. rgb Number of colors for color images. Applicable only to displays medium with 8 bits/pixel. Valid values: none, coarse (27 colors), medium (64 colors), fine (125 colors). safe Run WiT in safe mode. Can only be specified as a command line option. N.A. saveConfig Save configuration on exit. Valid values: 0 (no auto-save), 1 (auto-save). 0 scale Scale to use for igraph. Valid values: 0.1 — 10 1 scheme Color scheme to use for workspace and sub-graph windows. Valid light values: color, light, dark, custom. showGrid Grid visibility on igraphs. Valid values: 0 (off), 1 (on). 1 showStatus Show status window on start-up. Valid values: 0 (do not show), 1 (show). 1 snap Snap to grid when editing igraphs. Valid values: 0 (off), 1 (on). 1 speed Execution speed. Valid values: turtle, boy, rabbit, warp. boy statusWin Position and size of the WiT status window. Four integers: upper left X, upper left Y, lower right X, lower right Y. 0 0 300 170 view Display a data object on start-up. Valid values: any valid WiT data object file name. None 107 Command Line Options Command line options override any default or registry settings. The option names used on the command line are the same option names that appear in the system registry, but with a dash (‘–’) in front. For example, to set the execution mode to script, the WiT window to position (200,200) with a size of 400×300, and to load the history file myScript on startup, use these command line options: -mode script -position 200 200 400 300 -open myScript Safe Mode Sometimes WiT may be left with an unusable configuration. For example, the operator icon cache may be incorrect because some icons have been modified outside of WiT, libraries that no longer exists may be referenced by WiT, and frame grabber drivers may have changed so that the stored settings are not longer appropriate, etc. When there are too many changes, it is sometimes easier to revert WiT to a 'known' and safe state so that it can be reconfigured. For this purpose, WiT provides a safe mode start up option. You can start WiT in safe mode by one of the following methods: • • From the Windows Start button, select Start/Safe icon from the WiT program group. From the Windows Start button, select Run. Then type "wit -config safe" and press the OK button. System Registry You can optionally instruct WiT to store the current GUI environment in the system registry by selecting the Tools/Save config menu item. All subsequent WiT sessions then use the same configuration. You can have WiT automatically update the registry every time you exit WiT by checking the Save config on exit check box in the Options panel. The registry values are stored under the key HKEY_CURRENT_USER\Software\Coreco Imaging\WiT\Main You can use the registry editor to look at the stored values. But it is recommended that you do not change the values with the registry editor. If you want to change the settings, make the change from WiT. For example, to change the size of the status window, grab its resize corners and change its size. Then use Tools/Save config to save the changes. All subsequent WiT sessions will use the new size. 108 Color Configuration In order to display images accurately, WiT must be run with the Windows display set to high color or true color. You can customize the colors that WiT uses for the workspace, such as colors used for drawing icons, the workspace background, and the grid. To change a particular color, (e.g. the color used for operator parameters): 1. 2. 3. 4. 5. 6. 7. Select the Tools/Options menu item. The Options panel comes up. Select Custom for the Workspace control. Click the button. A color editing panel comes up. This is the familiar Color Panel but with a slight modification: on the bottom right of this panel is a choice stack for workspace object types whose colors can be changed. Choose the object type whose color you want to change from the choice stack, e.g. Parameter. Use the color disc or sliders to select a color Repeat the previous two steps for other colors you want to change. When you are satisfied with all the colors, click the button. Your customized colors are saved in the initialization file. Color Editor for Workspace Colors If you want to abort all changes you have made and revert to the original custom color definitions before you started, hit the Reset button instead of the button. If you want to remove all records of your current custom color definitions, click the Remove button. The next time you edit custom colors, WiT will copy the current color scheme (Light, Dark, or Color) to the custom color scheme, and then you can make changes starting from those colors. Workspace Object Color Types Background Background for igraphs, operator panels, etc. Foreground Links, probes, ports, and icon graphics. Selected Selected objects. 109 Busy Operators currently being executed. Labels Operator names above icons. Parameters Parameter names and values below icons. Icons Background of icons. IconBright Top and left borders of icons (for 3D effect). IconDark Bottom and right borders of icons (for 3D effect). Grid Grid on igraph. Directories The WiT distribution files are organized as follows: bin WiT executables. config Sample WiT configuration files. demo Example igraphs. images Sample images. h Header files for WiT development. ops WiT standard operator project directory containing operator and object definition files, icons, and help files. hardware Hardware support (e.g. frame grabbers) project directory. Read and Write Directories When WiT reads something from the file system, such as an igraph or an image, and if the file name is not an absolute path, WiT goes through a list of directories (search paths) to locate it. The first file that has the correct name is used. Search paths can be changed with the Object Locations search path panel from the WiT Manager. When WiT writes out something, and the file name is not an absolute path, then the current working directory is used. One exception to this rule is when an igraph has been read from the file system (as opposed to having been designed from scratch). If the igraph is saved using the File/Save menu item, the igraph will be saved to where it originally came from, regardless of where the current directory is. If you do not want this, use File/Save as instead. This will allow you to choose both a new name for the igraph and the directory to which it is saved. In any case, the directory that you saved the igraph to then becomes the current directory. 110 The current directory is set whenever a top level igraph is loaded (using the File/Open menu item) or when an object is viewed (using the File/View Object menu item). It is not set when a WiT operator reads or write a file. The only exception to this rule is the chdir operator, which will change the current directory. International Language Support WiT supports different languages by loading string files on start up. The following figure shows WiT running with simplified Chinese: Practically every word and phrase in WiT can be customized to any language. In other words, there is no reason that the Chinese version of WiT will need to display any English text at all. All the GUI labels, operator names, parameter names, igraph annotations, etc., can be presented in the preferred language. Of course, many scientific terms are used universally in all languages, so some English may still appear. But the reason is because that is how the term or concept is normally presented in the chosen language, rather than a limitation imposed by WiT. English (or ASCII to be exact) is still the default language for WiT. In the absence of translation files, WiT will run with English text. Since the language strings are loaded at run time, it is even possible for a regular WiT user to translate some or all of WiT into the language of his choice himself. 111 Choosing a Language There are several ways to choose a language, provided that it is already supported: • • When installing WiT, the WiT setup program will ask you what language you prefer. After a language is chosen, WiT will use it by default. Run WiT with the command line argument -lang, followed by the language of your choice. E.g. wit -lang japanese The name must be typed in exactly as specified, because it is used to search for the appropriate language files. Supported Languages Currently the following languages are supported: Language WiT Name ASCII (American English) no name required Simplified Chinese chineses Traditional Chinese chineset Japanese japanese Creating Translations for Operators WiT supports international languages for operators names, parameter names and values, and library names. All libraries have default ASCII (English) names. Other languages can then be supported by providing translation strings for some or all of the ASCII strings. For each library, in the same directory that contains the operator definition files, a translation file for each support language can be added. This name of this file must be the name of the library, followed by an underscore (‘_’), followed by the name of the language set in WiT (see User’s Manual), followed by a ‘.txt’ extension. For example, if you have a project named ‘myProg’, located in ‘C:\myWiT’, inside which is a library named ‘myLib’, then you should have the file: C:\myWiT\myProg\myLib\myLib.def To add support for the Chinese language (which in the standard WiT distribution is named ‘chinese’ in ASCII), you need to create the file: 112 C:\myWiT\myProg\myLib\myLib_chinese.def There are two columns in this file. The first column is either the group type or a string within the current group. The group type is sometimes followed by the group name in ASCII, if applicable. The second column is the translation for a string or group. A group type must be specified by a ‘#’ character in the first column. For example, the following is part of the Chinese file for the filter library: #title #common "In" "Out" "optimisation" #op "compass" #summary #opstrings "direction" "N" "NW" #op "conv1d" 䖛Ⓒ 䕧ܹ 䕧ߎ ᳔Շ࣪ 㔫Ⲭ 㔫Ⲭᨬ㽕 ᮍ৥ ࣫ 㽓࣫ ֵোो⿃ 113 Following is the list of valid groups: Group Type Description title Title of the library. common This group can be followed by a list of commonly used strings in any part of any operator within this library. For example, if the strings ‘in’ and ‘out’ are used by several operators as port names, parameter names, or parameter value strings, then putting their translations in the common will reduce the amount of typing you have to do. op Must be followed by the name of an operator in ASCII. The translation of the operator name can be optionally entered in the translation column. If you want to provide translations for parameter or value strings for an operator but not a translation for the operator name itself, you still have to create a group for the operator. opstrings This group can be followed by a list of strings used in any part of the current operator (declared with the op group). If a string is used more than once in this operator, the translation only need to be entered once. summary This group can be followed by a string which will be used as the summary line for the current operator. The summary line is used for the on-line help title and in the detailed view in the Operator Explorer. 114 Coreco Imaging Contact Information Sales Information Web site: www.imaging.com Email: [email protected] Technical Support Voice: (604) 435-2587 ext 9 Email: [email protected] Corporate Headquarters Coreco Imaging Inc. 7075 Place Robert-Joncas, Suite 142 St. Laurent Quebec H4M 2Z2 Canada Tel: Fax: (514) 333-1301 (514) 333-1388 US Sales Office Coreco Imaging Inc. 900 Middlesex Turnpike Building 8, Floor #2 Billerica, MA 01821 USA Tel: Fax: (781) 275-2700 (781) 275-9590 115 116