WHEELCHAIR SIMULATOR PACKAGE (Draft 2 4-Feb-88) * T. Mathews, M. Smith and J. McLaughlin Department of Electrical Engineering, University of Calgary, Calgary, Alberta, Canada T2N 1N4  *  Technical Resource Centre, Suite 100, 525 11 Avenue, S.W., Calgary, Alberta, Canada T2R OC9. Contact person: M. Smith. (403) - 220 - 6142 (MDT) FUNDING: This project was initially funded as a special project by the University of Calgary and the Calgary Celebral Palsy Association. DISTRIBUTION AND COPYRIGHT This package remains the copyright property of the authors. However, you are free to copy and distribute the package provided this notice remains with the package. You may not charge for any package that includes this program other than for the cost of the diskette to which it is copied. AMIGA user groups and the ubiquitous FRED FISK can copy and distribute it as per normal. If you find the package useful, then in the spirit of SHAREWARE, you are requested to send a tax deductable donation (suggested $20) to the Wheelchair Simulator Project, c/o J. McLaughlin at the Technical Resource centre address, so that another student can be hired to do further development work. WARNING: Although much care and attention has been given to the development and testing of the programs involved in this package, no warranty is given that the programs will behave exactly as described. PROGRAM HISTORY: The WHEELCHAIR SIMULATOR  was suggested as a project by J. McLaughlin to T. Mathews to fulfill the requirements for a graphics course taught by M. Smith. The course, ENEL513, is part of the program in COMPUTER ENGINEERING taught at the University of Calgary Electrical Engineering Department (UCEE). Further development work by T. Mathews and M. Smith occured across the summer of 1987 using funds provided by the University of Calgary and the Calgary Celebral Palsy Association. Credit is due to the therapists and patients of the Alberta Children's Hospital, Calgary who made many useful suggestions and tested the program. The MAKER program is based on a project developed by S. Worthington again to fulfill a course requirement for ENEL 513. It has been extensively modified by M. Smith who also designed the LYNNETTE graphical interface which allows the program to run on the AMIGA. FEEDBACK Please send your feedback to Dr. M. R. Smith, Department of Electrical Engineering, University of Calgary, Calgary, Alberta, Canada T2N 1N4. (403) 220-6142 (MST) who is currently directing the software development of the project (and having a fun time hacking when his new baby daughter lets him onto the terminal. Do you really think that 6 months is TOO early?) Please let him know what you think of the program. (I don't like the wall colours either but something keeps changing them back to those colours and I can't find what.) Any suggestions on different reinforcers etc., and information on bugs would be useful. In reporting bugs, please don't say "THIS DOES WORK". Say instead if you do this, and then this, and then that, then this happens. That way, I can trace what might be happening. For example, under certain conditions (which I can't replicate) all the bulletin boards and other objects move up to the highest horizontal wall. If this happens, select the DELETE ALL option and start again. If you can make it happen consistently, let me know how and I'll fix it. M. Smith 4th February 1988 PACKAGE CONTENTS This package of programs is designed to enable therapists to evaluate the types of control for a wheelchair used by the handicapped. It is also useful in providing some training for persons who need to become more familiar with the use of a wheelchair in a non-threatening and safe environment. The package is designed to be run on an Amiga computer with 512K memory, a colour monitor, a joystick, a keyboard and a mouse. The programs have been written in "C" and can be ported to other computers that have colour graphic capability (e.g. Apple G.S.). Because of the size of the program, the need for graphic capability and other factors, it is believed that porting to a computer such as an Apple 2E would not be feasable. The package contains 5 programs, CONTROLLER, MAKER, WHEELCHAIR3D, WHEELCHAIR2D, ANALYSIS and a series of predesigned floor plans. CONTROLLER: This is a program designed to allow the easy calling of the other programs in the package. People who become familiar with the AMIGA will probably find that the direct calling of the programs from the keyboard is a faster process. It also allows changing of the date, patient name and other useful utilities. MAKER: This program enables the user to design a floor plan through which the wheelchair operator can move. Walls, doorways, tables, cones and other objects can be placed as desired on the floor plan. Objects include arrows on the walls, happy faces and bulletin boards with messages. Other objects can be added by getting the authors in a good mood via buttering up their egos. Various options such as wheelchair speed and rotation rate can be set for use by the wheelchair simulation programs. WHEELCHAIR3D: This displays, in animated 3D, a view of the floor plan, bulletin boards, etc., as seen by a person seated in a wheelchair. The wheelchair can be moved through the plan or rotated by using the joystick. WHEELCHAIR2D: Designed to allow the user to become familiar with the floor plans generated by the therapist. It is more of a game than anything else but does allow some familiarity with the joystick to be obtained. If the game aspect of using the joystick is important in the therapy, buy a commercial package such as PACMAN rather than use this program. There are some very good (free) PUBLIC DOMAIN games available on FISH disks. Contact your local AMIGA user's group or computer shop for details. The games are free except for the cost of the disk onto which you copy them. ANALYSIS:  (not yet in existance.) This is designed to allow the therapists to analyse the progress of the patient. Suggestions as to what useful analysis should be made are requested. STARTUP PROCEDURE Connect your AMIGA computer with monitor, joystick and mouse as suggested in your manual. If you are using a custom joystick be careful when connecting to an AMIGA 1000 computer as they have a live (5 Volt) pin on the joystick connector. Make sure that your joystick has this pin disconnected. We have not yet found a joystick that causes a problem, but everybody has heard of Murphy. For the AMIGA 1000 computer, insert the KICKSTART disk into the disk drive and switch on the computer and monitor. With the AMIGA 500 and 2000 computer you simply switch on the computer: no KICKSTART disk is necessary. When requested by a prompt on the screen, remove the KICKSTART disk and insert the WHEELCHAIR SIMULATOR disk into the disk drive. In a short period of time, the CONTROLLER  program will load into memory and run itself. Using the BACKUP command of the controller program, you should first make copies of the wheelchair simulator disk and then put away one of the disks in a safe location as your master disk. It is suggested that one disk be used per patient. Once backup copies of the disks have been made, choose the options to run the MAKER or SIMULATOR programs as required. CONTROLLER The commands for running this program will appear on the screen. Type the first letter of the command and press the RETURN key. The command will become highlighted. Entering another letter and pressing RETURN will enable you to change your choice. Once the correct command has been selected, press return key again and the command will be executed. The available commands are A - ANALYSIS provides an analysis and print out of the results of the patient sessions using the simulators. (Not available Feb 1988.) B - BACKUP which causes a copy of the master disk to be made. It is suggested you make a new disk for each patient and keep your master disk in a safe location. C - CHANGE which enables you to change the floor plan or change the options for the simulation of an existing plan. You will be provided with a list of the names of the floor plans. Type in the name of the plan you wish to change and press the return key. D - DELETE which enables you to delete an unwanted floor plan from the disk. You will be provided with a list of the names of the floor plans. Type in the name of the plan you wish to delete and press the return key. To avoid accidental removal of the plans by the patient, a password is required to cause the deletion. The password is Get on with it L - LIST provides a list of the available floor plans on the current disk. M - MAKE will allow the making of a new floor plan. You will be provided with a list of the names of the floor plans already existing so you can choose another no conflicting name. Press RETURN when you are ready. P - PATIENT allows the changing of the patients name on the disk. The patient name is used as a file name into which to store the analysis results from the simulator. R - REMOVE removes the existing floor plans from the disk. Useful command if you can't find the master disk when a new patient comes in. Copy another patient's disk and then remove the plans from it. To avoid accidental removal, a series of passwords are required to cause the deletion. The passwords are Get on with it and or else!!!! T - TIME and DATE allows the setting of the current time and date of the session for use by the analysis program. Once the time and date are set, they are automatically changed by the computer until it is powered down. 2 - 2D simulation A list of the names of the floor plans available is first provided. Type in the name of the plan you wish to run and press return. 3 - 3D simulation A list of the names of the floor plans available is first provided. Type in the name of the plan you wish to run and press return. MAKER This program is a graphics program to allow simple interactive entry of a floor plan. Rather than entering random floor plans, it is suggested that the therapist build a floor plan of a situation with which the patient is familiar (e.g. hospital ward, home, school). DESCRIPTION If you are developing a new floor plan using the M - MAKE option of the controller program, you will be provided with a small box called a REQUESTER. This is to be used to enter in the name of the plan. There should be a small greyish box (the text cursor) inside the requester. If there is not, then move the mouse so that the arrow on the screen points into the black area of the requester and press the (left) button on the mouse. The text cursor should appear. (The text cursor will be in the wrong place when a requester appears on the screen, if the mouse buttons get touched shortly before the requester is due to appear. This fact should be remembered as it is a fairly common thing to cause happen in other parts of the controller program as you become familiar with the program and become quicker off the mark.) Enter in the name of the new plan and press the return key. If you have deliberately chosen the name of an existing plan, a requester will appear at the top of the screen to ask for confirmation. Use the mouse to move the arrow to point to either the OKAY TO DELETE or the CHOOSE NEW NAME option and press the left mouse button for the program to continue. If you used the CHANGE option from the CONTROLLER program, then the old floor plan will automatically be read in so that you can modify it. Using the MAKER program to create floor plans. A grid of grey lines will appear on the screen. This will be the WORKING AREA where the floor plan is designed. At the right of the screen, is a series of coloured boxes. These performed a function in the original program and since they looked pretty, I left them in. In version 2 of this program, these will be used for selecting objects (happy faces, etc.) in an easier way than currently done. On the left of the screen, a series of commands appear ( the MENU ). Move the red CROSS on the screen to one of the options by moving the mouse and press a mouse button. The command chosen should become highlighted in WHITE. If you choose the wrong menu item, move the cross to another option and press the mouse key twice: the first to unchoose the unwanted item, (highlight disappears), and the second time to choose the correct item. The MENU options are QUIT used for leaving the maker program and returning to the controller program. WRITE PLAN used to save the plan you have designed onto the patient disk. SHOW TRUE To make it easier to use the program, it is not necessary to place items such as happy faces and bulletin boards EXACTLY at the right location on a wall. You simply place it close to a wall. When the plan is saved, the program works out the nearest wall and moves the object to there. Since the program makes some decisions, the objects don't always move where you want them. Using the SHOW TRUE option allows you to find out what the computer will do. If you don't like what happens, use the CHANGE command to move an item to somewhere else. CHANGE This option allows you to delete incorrect items added to the floor plan, change the messages printed on the bulletin board, change the operating options of the simulation. For more details on the CHANGE command see the section entitleed "Building a floor plan". START Allows the initial placement and direction of the wheelchair to be set in the floor plan. BULLETIN Allows the placement of bulletin boards and messages. Details later. OBJECTS Allows the placement of tables, cones, arrows, happy faces. Details later. DOORWAYS Allows the placement of doorways in walls. Details later. WALLS Allows the placement of walls in the floor plan. The walls are the fundamental unit of the plan. Details later. BUILDING A FLOOR PLAN First select the WALL option. That option should become HIGHLIGHTED. Now move the cross-hair using the mouse. Place the cross-hair close to one of the intersections of the GRID in the WORKING SPACE and press the (LEFT) mouse button ONCE and RELEASE. You don't have to get very fussy of "how close is close" as the computer will choose the nearest intersection automatically. Now move the mouse in either a horizontal or vertical direction. A thin RED line will appear on the screen and move as you move the mouse. This is the wall that will later be drawn. Move the mouse UP, DOWN, LEFT and RIGHT until the wall suits your fancy. Then press the mouse button. The RED line will disappear and a YELLOW line will appear. This line does not move with the mouse and shows the final placement of the wall. DELETING  a wall that is in the wrong place can be done by the following stages Select the CHANGE option. A new MENU will appear. Select the DELETE LAST item option and the wall will disapper. Select the FINISHED option and the main menu will reappear. Now add any more walls that you want. You can choose other options and then come back to add even further walls. Adding DOORWAYS to existing walls is easy. Choose the DOORWAY option from the menu. Choose the middle of an existing wall with the cross-hair and press the mouse button. The red line will again appear and move with the mouse movement. This shows the location of the doorway. Make the doorway as large as you require and press the mouse button. A PURPLE line will appear in the wall. This represents the doorway. For best effects in the 3D simulation, always place doorways into walls. You can get some interesting features if the doorway is in the middle of no-where. Add all the doorways you want. They can be removed by using the change command in the same way as described for the walls. Adding OBJECTS to the floor plan can be down by first selecting the OBJECT menu option. Now move the cross-hair to the desired location on the working area and press the mouse button. A small white dot will appear on the screen marking the location chosen. At the bottom of the screen a requester will appear. You can type in the name of object you want and then press the return key. The object will then appear on the screen. The objects available are: ^ V < > which represent UP, DOWN, LEFT, RIGHT ARROWS. Note that UP is a term relative to the screen at the moment. When the simulation works, an UP arrow means an arrow that will point north (towards the top of the screen. Interesting visual effects can be acheived by putting an UP arrow near an EAST-WEST wall to provide additional reinforcement. Note that these objects should be placed CLOSE but not ON a wall if you want them to remain on the expected side of a wall when the floor plan is saved to a disk. T C represent TABLES and CHAIRS that can be placed as obstacles or as objects towards which the patient can be directed. These remain where you put them and do not move to the nearest when the plan is saved. H represents HAPPY FACES. Happy Faces appear on the wall WHEN the wheelchair gets close to them and is facing them. They appear as blank black areas on the wall until the wheelchair comes close. (KNOWN BUG:  Unpredicatable things happen if two happy faces are on the same wall. Happy Faces only appear in a very short range of wheelchair positons relative to the wall.) A useful reinforcer is the BULLETIN board. You are allowed up to 8 bulletin boards per floor plan. This is an artifical constraint and could be changed. You enter a bulletin board by selecting the bulletin menu option. Now move the cross-hair to the desired location and press the button. A small dot marks the location. A requester will appear at the bottom of the screen. Type in the desired message (maximum 25 letters aprroximately) and press the return key. The location of the bulletin boards are indicated by the symbols B1  through B8. The messages in the bulletin boards can be changed by selecting the CHANGE  menu option and then the bulletin sub-option in the new menu that appears. During the simulation, the message only appears on the bulletin boards when the wheelchair is close and in front of the bulletin board.. At other times, they appear as blank areas. The starting location of the wheelchair can be chosen via the START menu option. Select the starting location required in the floor plan and press the mouse button. A requester will appear asking for the starting direction to be indicated. The options are L R U D which correspond to LEFT, RIGHT, UP and DOWN. The start position can be changed by deleting the old position via the CHANGE command and selecting a new position. If no start position is chosen, then the program automatically selects the centre of the floor plan facing North (up). If this happens to be a wall then so be it. The CHANGE menu option allows the deletion of unwanted items, changing of simulation options, bulletin board messages. Selecting this item causes a new menu to appear with the following choices. FINISHED leaves the CHANGE option and returns to the main menu. DELETE LAST ITEM will remove the last item drawn on the screen. DELETE ITEM allows the deletion of a specific item or group of items. Once selected, move the cross-hair to a location a little to the left and below the object to be deleted: press the mouse button. Now move the cross-hair to a location a little to the right and above the object to be deleted. As you move the mouse, a small grey rectangle appears on the screen. When you press the mouse button, all items that start or end in the box will be deleted (never to return). WARNING:  If you try to delete a wall that is touching another wall, it is difficult not to delete both walls. If you do accidently delete an unwanted wall or two, then put them back using the WALL command. DELETE ALL allows the deletion of everything in the plan. The name of the plan remains. If you want to completely delete a plan, then the DELETE option in the CONTROLLER program allows you to do this. BULLETIN allows the changing of the messages in the bulletin board. On selection of this item, a requester will appear. Type in the bulletin board number you want to change. Another requester will appear showing the old message. You can edit the message by using the arrow keys to the right of the keyboard, the backspace key and the normal keyboard keys. Press the return key when you have an acceptable message. The arrow keys at the side of the keyboard allow you to before some editting on the old message rather than simply deleting it using the back space key. OPTIONS allows the changing of the options used by the simulator when it runs. The options are f F S (default S) name FLASH turn the FLASH off/on or replace it by a STOP sign respectively. The flash is used to indicate when the wheelchair runs into something. The lack of some indication that the wheelchair has run into something is confusing. However, the flash can be an undesired reinforced. F0 F1 through F8 (default F0) name FONTS allowing the size of the letters used on the bulletin board to be changed. (Only font 0 is present on this issue) J1 J2 through J5 (default J1) name JOYSTICK controls the momentum of the wheelchair. Without this control, the wheelchair does not stop instantly you release the joystick. Larger numbers means that the joystick must be held for a longer period of time before any action occurs. (At time of writing, this was not behaving in the manner expected.) l L (default L) name LINES places LINES off/on the floor of the simulator. This is a very useful visual clue in the 3D simulation. P1 P2 through P5 (default P1) name PADS places a set of WHEELCHAIR FOOT PADS on the front of the screen to allow visual positioning of the wheelchair. Only P1 means anything as we can't decide on useful shapes (arm rests or what have you.) R1 R2 through R100 (default R11) name ROTATION controls the rate of rotation of the wheelchair. This should be about 7/10 of the value of the SPEED option for reasonable looking 3D simulations. S1 S2 through S100 (default S16) name SPEED controls the speed of forward motion of the wheelchair during each frame of the animation. T1 T2 through T100 (default T8) name TIME controls the time interval (in 1/10 secs) at which the screen updates. It controls the animation rate of the screen. Making the SPEED and TIME options both smaller, means that the movement through the floor plan will be smoother. However, if the floor plan is complicated with many walls and objects, the time for each animation frame may change, which is confusing for the patient. Z0 Z1 through Z4 (default Z2) name ZOOM controls the zoom factor used to display the floor plan in the 2D simulation. Value Z0 is only useful for providing the patient with an indication of what the floor plan looks like. NOTE: If this program is run directly from the AMIGA command line rather than from the CONTROLLER program then the syntax is maker planname change an old floor plan or maker to make a new floor plan. 3D SIMULATION and 2D SIMULATION These run automatically from the controller program. When the 3D version is run, a blue screen will appear. Pressing the joystick will cause the simulation to start. Joystick forward/back movement will cause the scene to move relative to the wheelchair. Left and right joystick movements cause the chair to rotate. These actions follow what is to expected if a real wheelchair was moving. In the 2D version, the joystick movement causes the wheelchair to move on the screen in the same way that the joystick moves and not a real life movement. To exit the simulators, hold down on the joystick button for a count of about 5 - 8 seconds and then release the button. Pull back on the joystick. This removes the chances of the patient accidently hitting the button and causing an unwanted stop. KNOWN BUG: The simulators can be stopped by hitting CTRL-C but this will not allow the simulators to be run again until the computer has been powered down. This might be fixed in a later release. NOTE: If this program is run directly from the AMIGA command line rather than from the CONTROLLER program then the syntax is wheelchair2d planname or wheelchair3d planname ANALYSER (Does not yet exist.) This is a program that analyses data collected by the simulation programs during a session with the patient. A session refers to the time spend on one floor plan at one sitting. The data collected includes floor plan name, session date, session duration, whether 2D or 3D simulator used, types and numbers of obstacles encounterd. Indications of the quality of joystick use are given by the number of times the joystick was released or the patient bumped into walls or other obstacles. The settings of the speed, rotation and other options are recorder. The commands for tunning this program appear on the screen. Type the first letter of the command and press the return key. The command will become highlighted. Once the correct command haaaas been chosen, press the return key again and the command will be executed. the available commands are A - ANALYSE graphs? information from several sessions. L - LIST provides a list of sessions according to date. P - PRINT provides a hardcopy printout of one of the sessions if a printer is connected to the computer. S - SCREEN sends the data printout to the screen. The format of the printout is as follows 1. Name of the patient. 2. Date of the session. 3. Duration of the session. 4. Floor plan name and whether 2D or 3D. 5. List and number of obstacles used. 6. Total number of obstacles. 7. Number of times patient bumped into walls. 8. Number of times patient bumped into tables or other obstacles. 9. Number of times joystick was released (i.e. to determine the quality of joystick use.) 10. Directions patient travelled (i.e. the number of times patient moved forward, reverse, left and right) 11. Settings of the options used in the simulation (i.e. reinforcers, speed, rotation rates etc.