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:
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:
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:
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.
The ImageNavigator object takes two parameters:
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:
The last section demonstrated how to instantiate the Image Navigator object witht the required parameters. There are a number of optional parameters that can be used to alter the default behavior of the Navigator. These options are:
Changes to the options can be made after the object is instantiated by calling the SetConfig method.
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:
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 25.
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:
The second argument defines the type:
The third argument defines the 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:
The Pictometry Navigator API provides a number of events to which applications can register callbacks. There are 4 types of events:
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.
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).
The view port may be resized by calling the SetViewerSize method.
Mouse panning can be disabled/enabled using the SetMousePan method.
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.
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.
Bookmarking an Image
To bookmark the currently visible image, call the GetBookmark method. This method returns a string that can be used at a later time to return to the current image. To goto to a bookmarked image call the GotoBookmark method. This method takes the string returned from GetBookmark
For authorized users, there is an API method to export an image.
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,image and options fields.
The type field indicates the export data:
The image field indicates the image format:
The options field contains additional export options:
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:
Printing an Image
For authorized users, there is an API method to print an image w/o Overlays.
The Print 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 optional second argument, cfg, is an object that contains fields that alter the print functionality.
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 cfg object contains these fields. Only set the fields you wish to change:
NOTE: The print URL is a one-time use only.
In the default case, a call to Print results in a print dialog box.
If a callback method is given, the print URL is returned and no print job is submitted.
The object returned in the callback has 3 fields:
The example below illustrates the method calls:
The Pictometry Navigator supports a variety of objects that can be overlayed onto an image. These objects are:
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.
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.
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.
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.
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.
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.
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.
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.
NOTE: Multiple lines can be specified by placing a new line '\n' into the string to break the lines.
See Text for a complete description.
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.
A Feature is a container object that provides a display and query mechanism for GIS layers within a Web Feature Service (WFS). This implementation differs from other Image Navigator objects in that the location coordinates come from WFS and not from the user. This arrangement has a number of advantages:
There are some Navigator support methods that can be used in conjunction with a Feature:
NOTE: These fields are optional. Only specify the fields you wish to change.
NOTE: Setting fillColor or fillOpacity automatically turns the fill flag to true. It's only necessary to explicitly set the fill flag if you wish to use the default color and opacity or you wish to disable fill.
Display Modes
The Feature object supports two methods for display:
The display mode is changed via the SetDisplayMode method or can be passed in the configuration object at Feature creation. See example below.
When operating in Bounding Box (Bbox) mode, the API does not display any feature until a call to SetBoundingBox is made.
Query Method
The Query method takes an image x/y coordinate, an array of feature elements and a callback. The callback returns an object containing the associated data. The returned object is populated by fields with the same name as those fields passed to the Query() method. See example below.
Auto Label
A Feature can use one of the WFS fields as a label. See the configuration object in the example below.
Using Non-Pictometry WFS
In cases where it is desirable to retrieve features from a non-Pictometry source, the Feature object can be configured to query data from any WFS server that is accessible on the Internet. The Feature configuration parameter has a wfs object. This object has the following fields:
Limitations
See Feature for a complete description.
Example: Query the API for the Feature types.
Example: Create a Feature object for the 'parcels' layer.
Example: Create a Feature object for the 'parcels' layer with Auto Label.
Example: Create a Feature object using a non-Pictometry WFS server for the 'parcel' layer.
Example: Query the Feature object for the schema.
Example: Query the parcel 'owner' and 'addr' fields.
Streets is a container object that provides a mechanism for overlaying streets and highways onto Pictometry images. It is derived from Feature.
The Streets object accepts configuration for the color, weight and opacity of the street centerlines. The fields are:
NOTE: These fields are optional. Only specify the fields you wish to change.
Example: Create a Streets object for the 'streets' layer.
The Pictometry Navigator supports a variety of tools to perform measurements on an image. These tools are:
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 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:
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.
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:
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:
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:
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:
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:
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:
To measure perimeter using a freeform line:
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:
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:
See Distance Result for a description of the fields.
Measuring Standard Area
To measure standard area:
To measure area enclosed within a freeform line:
Measuring Area Using Line Segments
To measure area within a polygon defined by line segments.
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:
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:
Measuring Vertical Area
The Height tool has a limited capability to measure the rectangular area of a vertical object:
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:
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:
Measuring Angles
To determine the angle of an object:
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:
Measuring Differential Elevation
To measure the difference in elevation of two points:
In addition, the returned measurement contains an array called profile that provides an elevation profile along the line connecting the start and end points. Each element of the array contains an x, y and elevation field for each posting along the line. The default posting distanc is 5 meters, however, this can be overriden. See SetToolOptions for details on changing the posting distance and unit.
See Elevation Result and Elevation Profile 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:
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:
The region is retrieved by calling GetSelectedArea
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:
See: Distance Units
Area Units
Units for area measurements are set by calling the SetAreaUnit method. The API supports the following units:
See: Area Units
Location Units
Units for location coordinates are set by calling the SetLocationUnit method. The API supports the following units:
See: Location Units
Angle Units
Units for angles are set by calling the SetAngleUnit method. The API supports the following units:
See: Angle Units
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.
There are optional fields for the param object. See Optional Configuration Parameters.
Optional Configuration Parameters
Performing a Search
See: SearchRange
See: Pol.VI.ImageLevel
See: Pol.VI.ImageType
See: Pol.VI.Orientation
Events and Event Handling
See: Events for a complete list.
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.
Ancillary Events are those that do not conform to the standard Image, View, or Info events. The callback object contains specific data fields related to the type of event. These events are defined below.
See: AttachEvent and DetachEvent
Panning, Scaling and Viewport Sizing
Image Navigation
Exporting an Image
See: ExportTypes.
See: ImageFormats.
See: ImageOptions.
Overlay Manager
The current implementation supports layers with the following shape types:
Each shape type can have its own configuration. The fields are:
NOTE: All 3 fields are required.
Measurement Tools
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.
Using the Measurement Tools
IMPORTANT: This feature is available ONLY for the Distance Tool.
NOTE: If your keyboard does not have a number pad, press and release the "p" key instead.
Measuring Area Using a Freeform Line
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:
IMPORTANT: These features are available ONLY for the Height Tool.
NOTE: The returned latitude/longitude is in the WGS-84 datum.
The returned measurement contains the difference in elevation (rise) and the distance between the points (run). These values can be used to determine slope.
Measurement Units
The default distance unit is: Feet.
The default area unit is: Square Feet.
The default location unit is: Degrees.
The default angle unit is: Degrees.
Proxy Server
