Introduction
This article describes an easy approach to building a simple image mapping utility that may be used to mark and store points as pixel based coordinates from an image file or directly from a web page. The application is capable of capturing a collection of points, and it allows the user to name and save a point collection established using the tool into a text file.
The application could be used to do things such as to digitize an image by collecting points from key features in the image. For example, if one were to want to collect sizing and spacing information on an analog display for the purposes of defining a method for creating a digital version of that device, the application could be used in conjunction with a 1:1 scale image of the device to determine where to draw lines, add text and size text, etc. For web development, the application could be used as an aid to defining sizes and shapes of areas used in an image map.
Upon initialization of the application, the user may operate in either of two modes:
- By loading an image file directly into the application, or,
- Setting the application�s opacity to allow the user to view objects beneath the application.
In either case, once an image is loaded or made visible through the application, the user may mouse around the edges of an object to view the coordinates at any given point. If the user wants to capture the points and save them into a file, they may right click on the application to expose a context menu. The menu contains options to start and stop recording. Once start recording is selected, the application will store the coordinates for each selected point and will continue to so until the user selects stop recording. Once stop recording is selected, the application will expose a save file dialog and will capture the user defined file name and path from that dialog, this information will be used to store the entire point collection saved up until that point.
Figure 1 Image Mapping Utility in Use
Figure 2 Text File Output of Application Stored Points
Getting Started
In order to get started, unzip the attachment and load the solution into Visual Studio 2005. Examine the Solution Explorer and note the files contained in the project:
The contents of the solution show that it contains a single project entitled, �ImageMapper�. This project contains a single form class called �frmMain�. The frmMain.vb class contains is the only class contained in the project.
A quick check of the references will reveal that only the default class libraries are contained in the project.
The Code: The frmMain Class
The frmMain class contains all of the code used within the application. This class imports System.Text and System.IO which are used for storing the point data into a text file.
The form itself contains a menu with these options:
- File
- Load Image File option
- Exit Application option
- Crosshairs
- Color option
- Visibility Option
- Opacity
The form also contains a context menu which is associated with a picture box control; its contents are:
- Start Recording
- Stop Recording
- Cancel
The window contains a picture box which has its dock property set to full. The class also has an open file dialog, save file dialog, a color dialog, and a tooltip.
Following the imports and class declaration, the first section of code in the application is a declarations region which includes the following variable declarations:
#Region "Declarations"
Private mCrosshairs As Boolean
Private mLineColor As System.Drawing.Color
Private mRecord As Boolean
Private mPoints As SortedList
Private mPointCount As Integer
#End Region
- The crosshairs variable is used to determine whether or not to display the crosshairs at the current mouse position. If the variable is set to false, the crosshairs will not be shown and the user will see only a standard cross shaped cursor. With the variable set to true, the user will be shown full screen crosshairs centered on the present position of the mouse pointer. The crosshairs were intended to provide an aid to setting points along edges.
- The line color variable is used to store a color used to draw the crosshairs.
- The record variable is used to determine whether or not the application will store the user�s left mouse clicks at points.
- The points variable is a sorted list that is used to temporarily store the point collection as the user adds points to be saved.
- The point count variable is used to keep track of the number of points saved in the sorted list.
Following the declarations, the next bit of code in the application is the form constructor; this block is used to set some of the variables upon initialization of the application. That code is as follows:
Public Sub New()
InitializeComponent()
mLineColor = Color.Crimson
mPointCount = 0
Me.DoubleBuffered = True
mCrosshairs = True
End Sub
The next bit of code is the load image file menu option�s click event handler; that code is as follows:
Private Sub LoadImageFileToolStripMenuItem_Click(ByVal sender _
As System.Object, ByVal e As System.EventArgs) _
Handles LoadImageFileToolStripMenuItem.Click
Dim openFile As New System.Windows.Forms.OpenFileDialog
openFile.DefaultExt = "bmp"
openFile.Filter = "Bitmap File (*.bmp)|*.bmp" & _
"|Jpeg File (*.jpg)|*.jpg|Gif File
(*.gif)|*.gif"
openFile.ShowDialog()
If openFile.FileNames.Length > 0 Then
Dim img As New Bitmap(openFile.FileName.ToString())
PictureBox1.Image = img
PictureBox1.Refresh()
End If
End Sub
This code is used to load an image into the application�s picture box control. The code opens an open file dialog box that permits the user to select a common image file from the file system; once the file�s name and path are defined based upon the user�s selection, the application creates a new bitmap from the file and sets the picture box�s image property to contain that image.
The next item in the file is the file menu�s exit option; that code is simple enough:
Private Sub ExitToolStripMenuItem_Click(ByVal sender _
As System.Object, ByVal e As System.EventArgs) _
Handles ExitToolStripMenuItem.Click
Application.Exit()
End Sub
The next code block is the crosshair menu�s color menu option click event handler, which code is as follows:
Private Sub ColorToolStripMenuItem_Click(ByVal sender As _
System.Object, ByVal e As System.EventArgs) _
Handles ColorToolStripMenuItem.Click
ColorDialog1.AllowFullOpen = True
ColorDialog1.AnyColor = True
ColorDialog1.FullOpen = True
If (ColorDialog1.ShowDialog() = _
Windows.Forms.DialogResult.OK) Then
mLineColor = ColorDialog1.Color
End If
End Sub
This code block exposes a color dialog and allows the user to select a color; that color is subsequently used to set the color variable�s value to contain the selected color. The application uses that stored color value to set the color of the crosshairs as they are drawn.
Next up is subroutine used to set all of the opacity menu�s subordinate options check marks to unchecked; this subroutine is called whenever the user selects a new opacity option:
Private Sub ClearOpacityChecks()
mnu100percent.Checked = False
mnu90percent.Checked = False
mnu80percent.Checked = False
mnu70percent.Checked = False
mnu60percent.Checked = False
mnu50percent.Checked = False
mnu40percent.Checked = False
mnu30percent.Checked = False
mnu20percent.Checked = False
mnu10percent.Checked = False
End Sub
Next up are the menu options used to set the application�s opacity; there are similar options for each of the opacity settings exposed in the menu:
Private Sub mnu100percent_Click(ByVal sender As _
System.Object, ByVal e As System.EventArgs) _
Handles mnu100percent.Click
ClearOpacityChecks()
mnu100percent.Checked = True
Me.Opacity = 1
End Sub
After the opacity settings, the next block of code is the visibility menu item click event handler; this handler is used to set the crosshairs variable to true or false and to update the menu option�s check mark. With the crosshairs variable set to false, the crosshairs will not be shown, with it set to true, the crosshairs will be drawn at the present position of the mouse pointer:
Private Sub VisibilityToolStripMenuItem_Click(ByVal sender _
As System.Object, ByVal e As System.EventArgs) _
Handles VisibilityToolStripMenuItem.Click
If VisibilityToolStripMenuItem.Checked = True Then
VisibilityToolStripMenuItem.Checked = False
mCrosshairs = False
Else
VisibilityToolStripMenuItem.Checked = True
mCrosshairs = True
End If
End Sub
The next subroutine in the application is used to handle the picture box control�s mouse clicks:
Private Sub PictureBox1_MouseClick(ByVal sender As Object, _
ByVal e As System.Windows.Forms.MouseEventArgs) _
Handles PictureBox1.MouseClick
If mRecord = True Then
If e.Button = Windows.Forms.MouseButtons.Left Then
mPoints.Add("Point " & _
mPointCount.ToString(), _
e.X & ", " & e.Y)
mPointCount += 1
End If
End If
End Sub
This subroutine first checks the record variable to determine whether or not to record the point, if the application is in record mode, the subroutine then checks to see if the user left clicked the picture box control, and then it adds a point to the point collection as a string containing the point�s X and Y values. The sorted list�s key property is set to contain the text �Point� coupled with the current point count; after the point is added, the point counter variable is incremented to the next integer value.
After this bit of code, the next item in the class is the picture box control�s mouse move event handler:
Private Sub PictureBox1_MouseMove(ByVal sender As Object, _
ByVal e As System.Windows.Forms.MouseEventArgs) _
Handles PictureBox1.MouseMove
PictureBox1.Refresh()
ToolTip1.SetToolTip(PictureBox1, e.X & ", " & e.Y)
Dim pPen As New Pen(mLineColor, 1)
Try
If mCrosshairs Then
Dim g As Graphics
g = PictureBox1.CreateGraphics
g.DrawLine(pPen, e.X, PictureBox1.Top, _
e.X, PictureBox1.Height)
g.DrawLine(pPen, PictureBox1.Left, _
e.Y, PictureBox1.Width, e.Y)
End If
Catch ex As Exception
MessageBox.Show(ex.Message.ToString(), _
"Error", MessageBoxButtons.OK, _
MessageBoxIcon.Exclamation)
End Try
End Sub
This event handler is used to display the current mouse position in a tooltip associated with the picture box control. Further, if the crosshairs variable is set to true, the handler draws the crosshairs on the screen using the crosshairs color variable�s color value.
The next subroutine is the context menu�s start recording option click event handler:
Private Sub StartRecordingToolStripMenuItem_Click(ByVal sender _
As System.Object, ByVal e As System.EventArgs) _
Handles StartRecordingToolStripMenuItem.Click
If mRecord = True Then
MessageBox.Show("The application is " & _
"already recording.", "Recording", _
MessageBoxButtons.OK, _
MessageBoxIcon.Exclamation)
Exit Sub
End If
mRecord = True
mPoints = New SortedList
mPoints.Clear()
mPointCount = 0
End Sub
This handler checks to see if the application is already in record mode; if it is, the user is notified and the subroutine is exited. If the application is not in record mode, the application is placed in record mode, a sorted list is instanced and cleared, and the point counter variable is set to zero.
The next subroutine is used to handle the context menu�s stop recording option click event handler:
Private Sub StopRecordingToolStripMenuItem_Click(ByVal sender As _
System.Object, ByVal e As System.EventArgs) _
Handles StopRecordingToolStripMenuItem.Click
If mRecord = False Then
MessageBox.Show("Recording is not current enabled.", _
"Recording", MessageBoxButtons.OK, _
MessageBoxIcon.Exclamation)
Exit Sub
End If
mRecord = False
Dim strPoints As String = ""
Dim fname As String = ""
SaveFileDialog1.Filter = "Text Files|*.txt|All Files|*.*"
SaveFileDialog1.DefaultExt = "txt"
If SaveFileDialog1.ShowDialog() = _
Windows.Forms.DialogResult.OK Then
fname = SaveFileDialog1.FileName
End If
Try
Dim de As DictionaryEntry
For Each de In mPoints
strPoints = strPoints + de.Value.ToString()_
+ Environment.NewLine
Next
Dim SW As StreamWriter
Dim FS As FileStream
FS = New FileStream(fname, FileMode.Create)
SW = New StreamWriter(FS)
SW.Write(strPoints)
SW.Close()
FS.Close()
MessageBox.Show("Point file saved as " & _
fname.ToString())
Catch ex As Exception
MessageBox.Show(ex.Message.ToString(), _
"Error", MessageBoxButtons.OK, _
MessageBoxIcon.Exclamation)
End Try
End Sub
This subroutine checks to see if the application is in record mode and if it is not, the user is notified and the subroutine is exited. If the application is recording, the recording is disabled, a string variable used to contain the entire list of points is declared, and a string variable used to hold the file name and path is declared.
The string is then populated by iterating through the sorted list and adding each point pair to its content.
Next, a save file dialog is exposed and used to capture the user defined path and file name. After the path and file name are defined, a stream writer and file stream are created and the points string is saved to the file.
The last subroutine in the application is used to cancel recording. This handler is used to dispose of any existing point collection and disable recording; that bit of code is as follows:
Private Sub CancelToolStripMenuItem_Click(ByVal sender As _
System.Object, ByVal e As System.EventArgs) _
Handles CancelToolStripMenuItem.Click
Me.mRecord = False
Me.mPoints.Clear()
End Sub
Summary
This example was intended to provide an example of a utility that might be used as a constructive add to mapping images for a variety of purposes. I have used similar applications for a variety of purposes to include mapping images for the purposes of rendering similar displays within an application, and to validate that a design is defined in accordance with a specification that provides an image catalog based upon pixel coordinates.
