Pictometry Navigator™ API

Introduction
Initializing the API
Search and Display
Events and Event Handling
Image Panning and Scaling
Image Navigation
Export Options
Overlay Manager
Measurement Tools
Using the Measurement Tools
Measurement Units
Proxy Server

Introduction

The Pictometry Navigator is a Javascript API that contains the objects, methods, and events needed to develop web applications that integrate Pictometry images. The API contains 3 components that provide a variety of capabilities. These components are:

This document explains how to link to the Navigator and program its interface.

Access to the Image Service

The API operates in conjunction with an an Image Service over the Internet. Access to this Image Service is via a credentialed proxy server. You must have an authorized account and credentials in order to use the service. Contact your Pictometry Sales Representative for access.

Pictometry Image Libraries

Pictometry libraries consist of georeferenced oblique and orthogonal images. Images are captured at two levels of resolution herein refered to as:

Oblique images are typically captured in each of the four cardinal directions: North, East, South and West.

Orthogonal images are orthorectified and always oriented to true north.

For each geographic point in a coverage area there are potentially 10 unique views.

Asynchronous Operations

Some of the operations performed by the API require a call to a server. These calls are made asynchronously with the results and/or status reported to the application via a user provided callback function. The methods that require a callback are:

Active View

The API maintains the notion of an Active View. The view is Inactive from initialization until SetView is called and the onviewchange event has fired. The view is also Inactive during any Search or Navigate operations until the onviewchange event has fired. Any view specific calls to the API during an Inactive state are indeterminate. The IsViewActive method can be called at anytime to query the view state.

Documentation

The Pictometry Navigator API document describes the classes and methods. See the Change Log for bug fixes and new features.


Linking to the Pictometry Navigator API

To link to the Navigator add the following lines to the HEAD section of the web application.

Create a HTML DIV element

The Navigator requires an HTML DIV element that functions as the viewport for the images. This element specifies the initial dimensions and overflow properties. The DIV can be defined in the markup or created dynamically, but it must be bound to the Navigator before any operations can proceed. The overflow property is required to be hidden. This element is the container for all Navigator operations and should be considered off limits for any DOM operations not directly exposed by the API.

Create an ImageNavigator object

To create and initialize an ImageNavigator object requires just a few lines of code. The simplest way to do this is to create a function that gets called when the onload event fires on the BODY element.

NOTE: For the remainder of this document the created ImageNavigator object used in the examples is referred to as ImgNav. The declaration is shown below.

See: Init

Add the Init function call to the BODY onload event handler:


Performing a Search

A Search operation is required to begin viewing Pictometry images. The API Search method takes a location coordinate given in latitude and longitude. The coordinates must be in decimal degrees and in the WGS-84 datum. These coordinates may come from a mapping application, a geocoder or directly from the user.

The third argument to the Search method is a callback function. The completed search reports the results to the application via this callback passing a status object as an argument. See: Pol.VI.Status. An optional fourth argument can be specified that is passed back as the data field in tbe callback object.

Search Filtering

A filter can be applied to any search to modify the default API behavior. The SetSearchFilter method takes a SearchFilter object and uses it as the filter for all future searches. The range field specifies the order of the images. By default, the API returns the most recent images available. There are two built-in range filters:

See: SearchRange

In addition, a specific year or range of years can be set. The year should be given in the full, 4-digit format (ex: 2007). A range is specified by a list of comma-separated years. For example: 2006,2003 searches the 2006 then the 2003 libraries. The position of a year in the range defines its search order so that 2006,2003 could produce different results from 2003,2006.

For any location there may be multiple images that would satisfy a request. This is due to overlap in image capture and libraries that cover multiple years. The depth field defines the maximum number of images that should be returned for each view. The default is 5.

Displaying an Image

A call to the SetView method makes an image visible in the viewport. SetView takes 3 arguments that define the image. The first argument defines the level:

See: Pol.VI.ImageLevel

The second argument defines the type:

See: Pol.VI.ImageType

The third argument defines the orientation:

See: Pol.VI.Orientation

For views that have multiple images it is possible to cycle through them using the GetNextImage and GetPrevImage methods. Calling GetNextImage at the end of the list cycles back to the beginning. Calling GetPrevImage at the beginning of the list cycles to the end.

Once a view has been loaded via SetView, there are methods that allow the view to be changed based on individual image characteristics such as Level, Type or Orientation. These methods are:


Events and Event Handling

The Pictometry Navigator API provides a number of events to which applications can register callbacks. There are 3 types of events:

See: Events for a complete list.

Image Events are called back to the application with an object containing fields defining the mouse x,y and the image x,y coordinates on which the event was taken. There is also a type field that describes the type of event and a target field that is a reference to the object that took the event.

View Events are called back to the application with an object containing fields defining the view level, type, orientation and scale. Info Events are called back to the application with an object containing fields defining a numerical status code and a textual reason. See: AttachEvent and DetachEvent
Image Panning and Scaling

Images may be panned in one of two ways. Panning can be initiated by clicking and holding the left mouse button and moving the mouse within the viewport. Panning can also be invoked by calling the PanImage method. The PanImage method takes the number of pixels to pan in the x and y axes. Positive x-axis values move toward the right, whereas negative x-axis values move toward the left. Positive y-axis values move toward the bottom, whereas negative y-axis values move toward the top.

The API also has the notion of continuous panning managed by the ContinuousPan and StopContinuousPan methods. ContinuousPan takes the same arguments as PanImage and continues panning in the specified direction until another call to ContinuousPan changes direction or a call to StopContinuousPan stops the pan.

The image scale is specified as a floating point number representing the percentage of scale. For example, a scale of 50% is specified as 0.50 whereas a scale of 200% is specified as 2.0. The default image scale is 100% (1.0). Images can be scaled in increments of 1% or more by calling the SetScale method. The current scale factor can be obtained by calling the GetScale method.

NOTE: It is not recommended to scale out to less than 25% (0.25).

Mouse panning can be disabled/enabled using the SetMousePan method.


Image Navigation

Pictometry images are discrete, so panning eventually brings the user to the edge of an image. The API provides two distinct methods to navigate from the current image to the next.

  1. Approaching an image edge using the mouse causes the cursor to change from the default hand cursor to the walking man cursor. Clicking the image anywhere the walking man cursor is active fetches a new image set centered on the clicked point.
  2. Approaching an edge using the PanImage or ContinuousPan methods causes an edge detect event to be sent to the application. Upon receiving the event, the application can take whatever action is deemed necessary culminating in a call to the Navigate method. See the example code below.

The API is initialized in a non-navigation mode. A call to the the SetAutoNavigate method is required to enable the navigation modes described above.

See also: SetEdgeLimit and GetEdgeLimit method.


Export Options

For authorized users, there is an API method to export data.

The Export method takes as its first argument a region object that defines the image coordinates for the upper left/lower right of the portion to be saved. The second argument is a format object that contains fields that define the export type and image format. The results is a "Save As" dialog box that allows the user to save the data directly to the desktop.

An optional third argument to Export is a callback function. If specified, it instructs the API to return a URL in the callback instead of invoking a "Save As" dialog.

Limitations to URL export:

The region object can be obtained by calling the GetViewPort or GetSelectedArea methods. GetViewPort() returns the portion of the image visible in the view window. GetSelectedArea() returns the portion of the image captured by the Select tool.

The format object contains type and image fields.

The type field indicates the export data:

See: ExportTypes.

The image field indicates the image format:

See: ImageFormats.

Overlayed shapes can be exported with the image by calling the SetExportOverlay method. If set to true, a call to Export() will include all visible shapes.

The example below illustrates the method calls:

Viewport Sizing

The view port may be resized by calling the SetViewerSize method.


Overlay Manager

The Pictometry Navigator supports a variety of objects that can be overlayed onto an image. These objects are:

Once an object has been created it must be added to the current view by calling the AddOverlay method. A call to the RenderOverlay method is then required to render the object on the view.

IMPORTANT: If you have many objects to overlay, it is best to create and add these objects before making a final call to RenderOverlay. This reduces traffic to the server and should provide better performance.

To permanently remove an object from the view use the RemoveOverlay method.

The following examples demonstrate how to create and add the various overlay objects.

Overlaying a Marker

A Marker is simply an icon that is anchored to an image set at a specified coordinate. The Marker support various mouse events which can be called back to the application. The default marker is a teardrop icon.

A custom icon can be specified using the Icon, Size and Pixel objects. The examples below show how to create a default and custom marker.

See Marker and Marker Options for complete descriptions.

Overlaying an Element

A user defined HTML element can be anchored to an image set at a specified coordinate. You can declare a style sheet class that has the properties you desire for the element. Below is one example.

See Element and Element Options for complete descriptions.

It is a good idea to set the overflow : hidden property. This will keep any overflow in the element from spilling onto the image.

Overlaying a Point

A Point is a simple geometric point that can be anchored to an image set at a specified coordinate. The Point's color, weight and opacity can be specified.

See Point for a complete description.

Overlaying a Polyline

A Polyline is defined by an array of, at least 2, vertices that form a line segment or series of connected line segments that can be overlayed on an image. The Polyline's color, weight and opacity can be specified.

See Polyline for a complete description.

Overlaying a Polygon

A Polygon is defined by an array of, at least 3, vertices that form a closed shape. The Polygon's color, weight, opacity, fill color and fill opacity can be specified.

It is possible to define "cut-outs" or "donut holes" within a polygon such that there is an Outer Boundary and one or more Inner Boundaries. A polygon of this sort is defined by an array of arrays of vertices that form closed shapes. The first array defines the outer boundary with the subsequent inner boundaries defined by the other arrays like this:

var polygon = [[Outer], [Inner0], [Inner1], [Inner2], [...]];

IMPORTANT: There are some requirements and limitations to this type of polygon.

See Polygon for a complete description.

Overlaying a Circle

A Circle is defined by a center point and another point which is used to compute the radius or a center point and a distance that defines the radius. If a distance is used to define the radius, there is an optional field that specifies the units of the distance. The Circle's color, weight, opacity, fill color and fill opacity can be specified.

See Circle for a complete description.

Overlaying a Text Annotation

A Text Annotation is anchored to an image set at a specified coordinate The Texts's color, font family, font size, font weight, font style and opacity can be specified.

See Text for a complete description.

Overlaying a Layer

A Layer is a container object that enables the efficient aggregation of certain shape objects. For example, a Layer could represent a collection of polygons or polylines that define a parcel layer or street centerline layer from a shapefile. There are potentially hundreds or thousands of shapes that comprise a layer and managing each shape as an independent object can incur performance penalties. This class can manage shapes as an aggregate, thereby reducing multiple objects to a single Layer object. The supported shapes are:

Limitations

One limitation of using the Layer class is when specifying the stroke color, weight and opacity and fill color and opacity. Because each supported shape type is an aggregate, these settings apply to every instance of a given type. You can set different values for each shape type, but every instance of that shape will be rendered with the same values.

A second limitation is in event handling. Events are registered against the layer itself and not against each shape. To determine the shape that caused the event, the GetShapeId() method is provided. GetShapeId() takes the image x,y of the event and attempts to match that to a shape.

See Layer for a complete description.


Measurement Tools

The Pictometry Navigator supports a variety of tools to perform measurements on an image. These tools are:

See: Image Tools

Measurement Operations

All measurement operations are started by selecting a tool via SetImageTool. This method takes an image tool and an optional cursor. If no cursor is specified, the default cursor for that tool is used. Measurements are accomplished by a combination of click and drag operations coupled with events. The following sections outline the events, methods and callbacks necessary to use the Image Tools.

Measurement Events

Measurement events are called back to the application when a tool is selected and the user measures on the image using the mouse. The callback object contains fields defining the mouse x,y and the image x,y coordinates on which the event was taken.

The onstartmeasurement event is fired when the mouse button is clicked. The purpose of this event is mainly informational. In most cases it is not necessary to register for it unless there is a specific need to indicate the beginning of a measurement to the user.

The onendmeasurement event is fired when the mouse button is released at the end of a measurement or an intermediate result has been requested. This event is REQUIRED. When this event is received the application should call the Measure method to compute the result.

The example code below illustrates how to handle the events: A sample Measurement Callback function is detailed below.

Computing the Measurement

To compute the measurement result requires a call to the Measure method which takes a callback function as an argument. As detailed in the last section, this call should be made after a onendmeasurement event has been received. The object returned in the callback contains the fields specific to the type of measurement. These objects are defined here:

Measurement Callback

Below is an example of one way to construct a measurement callback function:

Setting the Color and Line Thickness

The color and line thickness of the tools can be set using the SetColor() and the SetThickness() methods.


Using the Measurement Tools

The following sections outline the general user interaction required to use the various tools. These sections also detail any limitations and options available for a particular tool.

General Note: For Distance and Area measurements it is possible to measure to a point on the image that isn't currently visible in the view port:

  1. Follow the directions for Distance and Area given below.
  2. When the edge of the view port is reached and while still holding down the mouse button, move the cursor outside of the viewport.
  3. This will cause the image to pan in the direction of the cursor.
  4. Every move of the mouse will pan the image a little more.
  5. Continue to do this until the desired endpoint appears in the view port.
  6. Move the mouse cursor to the endpoint and release the mouse.

Measuring Distance Along a Straight Line

The Distance Tool enables you to calculate distance from a specific start point to a specific stop point on an image. You can use the Distance Tool to measure straight lines, freeform lines, and to calculate cumulative distances.

To measure distance along a straight line:

  1. Select the Distance tool using SetImageTool.
  2. Click a starting point on the image, hold down the mouse button, and drag to the ending point.
  3. Release the mouse button.

Measuring Distance Along a Freeform Line

The Distance Tool enables you to measure distances even when the path does not fall along a straight line.

To measure distance along a freeform line:

  1. Select the Distance tool using SetImageTool.
  2. Click a starting point and hold down the ALT key while you drag the mouse. You will be able to draw a line of any shape, not just a straight line. Distance is measured along the path the mouse travels.
  3. Release the mouse button.

Measuring an Intermediate Distance Along a Straight Line

The Distance Tool enables you to measure distances without releasing the mouse button.

To measure intermediate distance along a straight line:

  1. Select the Distance tool using SetImageTool.
  2. Click a starting point on the image, hold down the mouse button, and drag to an intermediate point.
  3. Press and release the Shift key.
  4. Drag to another intermediate point and repeat Step 3.
  5. Repeat Step 4 as needed.
  6. Release the mouse button.

Measuring the Cumulative Distance along Line Segments

The Distance Tool enables you to measure the cumulative distance along multiple line segments.

To measure cumulative distance along multiple line segments:

  1. Select the Distance tool using SetImageTool.
  2. Click a starting point on the image, hold down the mouse button, and drag out the first line segment.
  3. Press and release the v key. This drop a vertex at this point.
  4. Drag to out another line segment in any direction and repeat Step 3.
  5. Repeat Step 4 as needed.
  6. Release the mouse button.

Measuring Perimeter

The Distance Tool enables you to measure the distance around the outside edge of an object. You can measure the perimeter of a square or rectangle using a parallelogram. You can measure the perimeter of a freeform shape using a freeform line.

To measure perimeter using a parallelogram:

  1. Select the Distance tool using SetImageTool.
  2. Click a starting point and draw a straight line along the edge of an object.
  3. Press the CTRL key and drag the mouse along the adjoining edge of the object. The tool creates a boxed line around the perimeter of the object.
  4. Release the mouse button.

To measure perimeter using a freeform line:

  1. Select the Distance tool using SetImageTool.
  2. Click a starting point and hold down the ALT key while you draw a line around the outside of the object. For the best results, ensure that the start point and stop point are joined.
  3. Release the mouse button.

Measuring the Distance with Elevation Variances

The Distance Tool can be set to allow "Walk the Earth" measurements which use the elevation data of the area being measured when calculating the total distance. This feature works best on images with many elevation changes.

To measure distance including elevation data:

  1. To enable Walk The Earth distance measurements, call SetToolOptions with the configuration parameter wte set to true.
  2. Perform a distance measurement.
  3. Repeat Step 2 for each distance as needed.
  4. To disable Walk The Earth distance measurements, call SetToolOptions with the configuration parameter wte set to false.
IMPORTANT: This feature is available ONLY for the Distance Tool.

Measuring Distance Across Images

The Distance Tool enables you to calculate distance from a start point in one image to a stop point on another image.

To measure distance across images:

  1. Select the Distance tool using SetImageTool.
  2. Click a starting point on the image.
  3. Navigate to a new image.
  4. Click and hold the mouse button at a stopping point on the new image.
  5. Press and release the + key on the keyboard number pad.
  6. Release the mouse button.
NOTE: If your keyboard does not have a number pad, press and release the "p" key instead.

See Distance Result for a description of the fields.

Measuring Standard Area

To measure standard area:

  1. Select the Area tool using SetImageTool.
  2. Select a starting point, hold down the mouse button, and draw the first line along one edge of an object.
  3. Press and hold the CTRL key. Then drag the mouse along an adjoining edge of the object. The tool creates a boxed line around the perimeter of the object.
  4. Release the mouse button and CTRL key.
Measuring Area Using a Freeform Line

To measure area enclosed within a freeform line:

  1. Select the Area tool using SetImageTool.
  2. Press and hold the ALT key. Select a starting point, hold down the mouse button and draw a freeform line. For the best results, ensure that the start point and stop point are joined. Any gap between the start and end point is automatically closed.
  3. Release the mouse button and ALT key.

Measuring Area Using Line Segments

To measure area within a polygon defined by line segments.

  1. Select the Area tool using SetImageTool.
  2. Click a starting point on the image, hold down the mouse button, and drag out the first line segment.
  3. Press and release the v key. This drop a vertex at this point.
  4. Drag to out another line segment in any direction and repeat Step 3.
  5. Repeat Step 4 as needed. For the best results, ensure that the start point and stop point are joined. Any gap between the start and end point is automatically closed.
  6. Release the mouse button.

See Area Result for a description of the fields.

Measuring Height

The Height Tool enables you to measure the height of an object in an oblique image.

To measure the height of an object:

  1. Select the Height tool using SetImageTool.
  2. Select a starting point at the base of an object (such as the base of a building), hold down the mouse button, and drag to the ending point.
  3. Release the mouse button.
NOTE: Normally, you must measure upwards starting at the base of an object at ground level to obtain the most accurate height. Measuring from the top of an object down will not result in the same value as measuring from the bottom up. However, by setting the Top-Down option, an accurate top-down height measurement can be done. The setting of this option is shown below:
  1. To enable Top-Down height measurements, call SetToolOptions with the configuration parameter topdown set to true.
  2. Perform a height measurement.
  3. Repeat Step 2 for each height as needed.
  4. To disable Top-Down height measurements, call SetToolOptions with the configuration parameter topdown set to false.

IMPORTANT: When using topdown measuring you must draw all the way to the ground in order to get a good measurement. A partial topdown measurement will not be accurate.

NOTE: The true height of an object is measured from a point on the ground plane to a point above and perpendicular to the ground plane. It is natural to draw a height line that appears to be perpendicular, but in reality, is somewhat skewed by the obliqueness of the image. The API automatically compensates for this in the height calculation, but it is sometimes useful to be able to see the actual perpendicular. To accomplish this, the API provides a Draw Plumb Line option to the Height Tool as explained below:

  1. To enable Draw Plumb Line height measurements, call SetToolOptions with the configuration parameter plumb set to true.
  2. Perform a height measurement.
  3. After releasing the mouse button the computed plumb line is automatically drawn.
  4. Repeat Step 2 for each height as needed.
  5. To disable Draw Plumb Line height measurements, call SetToolOptions with the configuration parameter plumb set to false.
IMPORTANT: These features are available ONLY for the Height Tool.

See Height Result for a description of the fields.

Determining Location

The Location Tool enables you to determine the latitude/longitude of an object in an image.

To determine the latitude/longitude of an object:

  1. Select the Location tool using SetImageTool.
  2. Click the desired location on the image.
NOTE: The returned latitude/longitude is in the WGS-84 datum.

See Location Result for a description of the fields.

Measuring Compass Bearing

The Bearing Tool enables you to measure the degree of angle of an object in relation to true North. You can also measure the angle of a particular area in an image by designating three separate points from which to measure.

To determine bearing:

  1. Select the Bearing tool using SetImageTool.
  2. Click a starting point on the image and draw a line.
  3. Release the mouse button.

Measuring Angles

To determine the angle of an object:

  1. Select the Bearing tool using SetImageTool.
  2. Click a starting point on the image and draw a line. Press and hold the CTRL key, then drag the pointer in a different direction.
  3. The line splits in two at the start point and enables you to draw a second line to represent a fork in the road or the angle of an object.
  4. Release the mouse button and CTRL key.

See Bearing Result for a description of the fields.

Measuring Elevation

The Elevation Tool enables you to measure the elevation (height above sea level) of a point in an image or to measure the difference in elevation between two points.

To measure the elevation of an object:

  1. Select the Elevation tool using SetImageTool.
  2. Click the desired point on the image.

Measuring Differential Elevation

To measure the difference in elevation of two points:

  1. Select the Elevation tool using SetImageTool.
  2. Click and hold the mouse on a starting point in the image.
  3. Press and hold the CTRL key, then drag the pointer to an end point.
  4. Release the mouse button and CTRL key.
The returned measurement contains the difference in elevation (rise) and the distance between the points (run). These values can be used to determine slope.

See Elevation Result for a description of the fields.

Measuring Pitch-Area

The Pitch-Area Tool enables you to measure the pitch angle and area of an object (such as the roof of a building), as well as the eave and peak height.

To determine the pitch-area of an object:

  1. Select the Pitch-Area tool using SetImageTool.
  2. Starting from the base of the eave. Click and hold a starting point on the image and draw a line upwards to the eave. Release the mouse button.
  3. Move the pointer to the base of the peak. Click and hold a starting point on the image and draw a line upwards to the peak. Release the mouse button.
  4. Click and drag out a parallelogram that covers the object.
  5. Release the mouse button.

See Pitch Result for a description of the fields.

Selecting a Region

The Select Tool enables you to define a rectangular region of the image.

To select a region of an object:

  1. Select the Select tool using SetImageTool.
  2. Click a starting point on the image, hold down the mouse button, and drag out a box.
  3. Release the mouse button.

The region is retrieved by calling GetSelectedArea


Measurement Units

The API provides setting for a number of different measurement units in the English and Metric systems. The following sections detail the Distance, Area, Location, and Angle units available and their default settings.

Distance Units

Units for distance measurements are set by calling the SetDistanceUnit method. The API supports the following units:

The default distance unit is: Feet.

See: Distance Units

Area Units

Units for area measurements are set by calling the SetAreaUnit method. The API supports the following units:

The default area unit is: Square Feet.

See: Area Units

Location Units

Units for location coordinates are set by calling the SetLocationUnit method. The API supports the following units:

The default location unit is: Degrees.

See: Location Units

Angle Units

Units for angles are set by calling the SetAngleUnit method. The API supports the following units:

The default angle unit is: Degrees.

See: Angle Units


Proxy Server

The Pictometry Navigator is built using AJAX technology using the built-in browser object XMLHttpRequest. Web browsers impose a security restriction on calls from XMLHttpRequest. This restriction prevents a script or application from making a connection to any web server on a domain other than the one that originated the request. To circumvent this restriction, a proxy is needed on your application web server to access our image database.

The proxy server also has the responsibility to digitally sign each search request so that it can be authenticated by our servers. This requires a Pictometry supplied Signature Key and the ability to compute a MD5 or SHA1 hash. The algorithm for computing a digital signature is as follows:

Proxy Server Examples

Here are two examples of a proxy server. One is written as an ASP .NET Web Handler and the other is written in PHP. The proxy can be written in whatever language you desire as long as it conforms to the above specification. You can, of course, use one of the provided samples and modify it as needed.