MouseTrap


Installation:
Windows: Prior to running the MouseTrap installer, make sure you have a Java Runtime Environment, Version 1.5 installed. If this is the case simply run MouseTrap.exe and follow the Installer's instructions.
Mac OSX: Mount the disc image and double click the MouseTrap package, then follow the installer's instructions.

Introduction:
MouseTrap originated in a scenario, where we had to control a Mouse-driven Flash project from an OSC equipped motion tracking system. This operating mode - hijacking the mousepointer - has been extended and is now one out of four the programm offers. All operating modes share the same parameters, so this will first describe the interface and setting of parameters and then introduce the operating modes:

Interface
The Interface is devided into 2 (+1) parts and a little dialog window. In the upper third of the application window you find from left to right:
  • On(Off button - this lets you activate or deactivate mouse capturing or dataconversion. Useful when you need to temporarily need to turn off mouse remote control to work on the hijacked machine directly.
  • In/Out button: toggles between remote control and control mode. In remote control mode the window is slim as above. In control mode it is expanded and a "sensoractive" area is added on the bottom.
  • Control port popup: Selects between Midi and OSC operation and also sets the MIDI port used.
  • Channel textfield: Only valid for Midi operation. Sets the midichannel MouseTrap reads and sends.
  • Setup button: opens the settings dialog.

The lower two third of the window vary between MIDI and OSC operation and are, same as the setings dialog, described below.

Operating parameters:
MouseTrap uses the same mapping of Midi/OSC messages to Mouse & Keyboard for all modes. That is: In controller mode it will send the Midi controllers that it reacts upon in remote control mode. The program stores settings internally and restarts as it was shut down.

Setting ports and control mapping:

  • Select either a MIDI input port or OSC from the upper ctrl port pop-up.
  • For MIDI operation select Controller numbers for Mouse x and y position from the lower popup menus. MouseTrap optionally reads high resolution here (14bit assembled from 2 CtrlChange Midi messages) . Enter note numbers (C1 = 36) into the textfields on the left. These notes will trigger the mouse buttons (mouse-down on note-on, mouse-release on note-off) or be triggered by mouse buttons. Controllers and notes can also be set from Midi: right click the text field or popup to set (it will turn red, indicating learn mode), then send the Midi you want MouseTrap to react upon. The scrollwheel is fixly mapped to MIDI pitchbend and the keyboard keys react upon and send notes with corresponding ASCI values.
  • For OSC operation set MouseTrap's receive port. The sending computer should open this port to connect to MouseTrap. For MouseTrap to send OSC enter a server IP and port number to open. Then edit the message headers for mouseposition, buttons etc on the OSC page of the settings dialog. See below.


Auto-hide will make MouseTrap immediately disapear in the taskbar / dock after launching. This is for autorun situations where the controlled application is what is to be seen.
Loop all MIDI through to MIDI out.
Convert incoming MIDI to OSC. This will transform the MIDI bytes that MouseTrap is set to read to OSC messages according to the set OSC headers and send them to the specified server. All other MIDI is ignored!
enable keyboard input & output
Lets you control a Mac from a PC by mapping "Ctrl" to "Apple" keys or vice versa.
MouseTrap optionally sends mirrored Controllers for mouse position (MIDI ctrl. nr are the set X & Y Ctrl.+1).
You may want to invert either mouseposition axis. Will also flip the optional mirrored value.
IP number or fully qualified name of the computer MouseTrap sends OSC to (loopback works as well)
Port number on said computer to open
When MouseTrap is to receive OSC, it should be routed to this port.
Instructs MouseTrap to send a "/" as the very first byte and to take one in account on receive.
Outgoing messages will be labelled "(/)MouseTrap" and only ones labelled like this will be read.
Header for mousecoordinates. Values are transmitted/read as 2 float values between 0 & 1.
Header for mirrored mousecoordinates.
Header for buttons. Values are send/read as two ints (button nr and state - 1 pressed, 0 released)
Header for the scroll wheel.
Header for keys. Values are send/read as two ints (ASCI value and state - 1 pressed, 0 released)
Operating modes:
  • Remote Control: Midi or OSC data as specified in the described GUI elements controls the computer MouseTrap is running on. The Application window is slim as shown above. This works regardless of wether MouseTrap is in the foreground or in the background. You should take into account, that MouseTrap does not hide the Mousepointer (this would work only long as the program is focussed). You will need to hide the pointer from the application you want to control.
  • Controller mode: MouseTrap sends MIDI/OSC as specified in the described GUI elements out the set control port. The application window is extended with another panel. This is the sensoractive area. Use this to turn the mouse into a handy synth-controller and to trigger sounds from mousebuttons & keyboard or whatever might come into your mind.
  • Blind VNC mode: This is a combination out of the previously mentioned ones. You will need two computers and two mousetrap installations. One should run in control, one in remote control mode. Both should be set to use OSC and the controller should connect to the remote controlled. You can then fully operate the remote controlled computer from the control one, execute programs, save documents, use copy/ paste. Whatever. This of course only makes sense when you can see the video output of the controlled machine, but it is a lot more responsive than traditional VNC, which is usually immensely slowed down by the desktop imagery that is also transferred via the network. So, given the controlled machine is connected to a large scale projection, this is definetely preferable to VNC. Can be very useful in professional presentation setup phases!
  • The fourth mode is a sideeffect and not very comfortable in its implementation, but both MIDI control and OSC control offer the option to transform and output received data to the other protocol. To convert MID to OSC set the appropriate checkbox in the dialog window. To convert OSC to Midi select a MIDI output port in the main window's OSC page. MouseTrap must be in remote control mode to do format conversion!


Prerequisites: Windows users may download Sun's JRE 1.5 from http://java.sun.com/j2se/1.5.0/download.jsp (pick the J2SE Runtime Environment (JRE) link, usually the third from the top) and the latest Quicktime from: http://quicktime.apple.com.


Windows is a registered trademark of Microsoft Corporation
Apple, Mac, Macintosh, MacOS X & Quicktime are registered trademarks of Apple Computer Inc.
Sun & Java are registered Trademarks of Sun Microsystems Inc.