Scripting the PinPoint Engine

PinPoint is an image-analysis and astrometric engine that can be scripted using any Windows Script language (e.g., Visual Basic Script or JScript), or from Visual Basic 6, Visual Basic.NET, C#.NET, Microsoft Office/VBA, etc. VBScript will be used in the examples below.

Basic Usage

To use the PinPoint engine, create in instance of a Plate object, then attach a FITS image to the created Plate. In VBScript:

  Set p = CreateObject("PinPoint.Plate")
  p.AttachFITS "C:\Images\test.fts"

At this point, all of the FITS header info is mapped into Plate properties. For a list of the FITS headers and their corresponding properties, see PinPoint 5.0 FITS Keywords. For example, to retrieve the date/time of the exposure start:

  StartTime = p.ExposureStartTime

Most PinPoint FITS properties are read/write, and may be changed by your script. If you want to write the modified FITS properties back to the image, use the Plate.UpdateFITS() method. For example, to add your email address into the EMAIL header field and have it written to the image:

  p.Email = "rdenny@dc3.com"
  p.UpdateFITS

Some of the FITS properties depend on the plate having been solved. There are the World Coordinate System (WCS) properties. The high-precision centerpoint coordinates, the vertical and horizontal plate scales, and the roll angle are only available when the image has been plate solved. WCS has a standardized format, so even if another program such as IRAF or Astrometrica has solved the plate, PinPoint will be able to read and use this information.

Scanning an Image

PinPoint can scan the attached image and produce a list of detected objects. To scan an attached image, set the Plate.ArcsecPerPixelHoriz and Plate.ArcsecPerPixelVert properties, then simply call Plate.FindImageStars(). Afterward, the ImageStars collection (a PlateStars collection), contains a list of the detected objects. Each item in the collection is a PlateStar object which has many properties describing the detected object, such as flux, X/Y coordinates, etc. You can sort this collection in various ways (e.g., by RA or flux). Be sure to read anout the PlateStars collection, it has some surprisingly powerful and useful methods!

For example, to list the X and Y coordinates of all of the detected objects:

  p.ArcsecPerPixelHoriz = 1.5
  p.ArcsecPerPixelVert = 1.5
  p.FindImageStars
  Set stars = p.ImageStars
  For Each star in stars
    WScript.Echo star.X & " " & star.Y
  Next

Looking up catalog stars

PinPoint can also create a PlateStars collection containing all of the catalog stars in the region of the image. For this, you need to set up more of the WCS properties (unless the plate has been solved). Besides Plate.ArcsecPerPixelHoriz and Plate.ArcsecPerPixelVert, you need to set Plate.RightAscension and Plate.Declination. You might want to get these coordinates from the Plate.TargetRightAscension and Plate.TargetDeclination properties. Many imaging systems put these approximate coordinates into the FITS header when the image is acquired. You can leave the roll angle alone, PinPoint is insensitive to roll angle and will solve regardless of its initial value of zero. Finally, you must specify the catalog type and path to the catalog database using the PlateCatalog and Plate.CatalogPath properties. Finally, call the Plate.FindCatalogStars() method.

For exampple, to list the catalog stars in the area of the image (by default including a 30% margin around the image itself):

  p.ArcsecPerPixelHoriz = 1.5
  p.ArcsecPerPixelVert = 1.5
  p.RightAscension = p.TargetRightAscension
  p.Declination = p.TargetDeclination
  p.Catalog = 3  ' Corrected GSC
  p.CatalogPath = "C:\GSC-1.1"
  p.FindCatalogStars
  Set stars = p.CatalogeStars
  For Each star in stars
    WScript.Echo star.Identification & " " & 
                 star.RightAscension & " " & _
                 star.Declination
  Next

Solving Plates

This is perhaps one of PinPoint's most useful operations. Once the plate has been solved, the Plate.RightAscension and Plate.Declination properties contain highly accurate coordinates for the image center point. In addition, the other WCS properties such as Plate.RollAngle, Plate.ArcsecPerPixelHoriz and Plate.ArcsecPerPixelVert also contain highly accurate values. To solve a plate, set up the approximae WCS values, then call the Plate.Solve() method. This implicitly calls the Plate.FindImageStars() and Plate.FindCatalogStars() methods, so you don't have to call them.

Once solved, the Plate.ImageStars, Plate.CatalogStars, and Plate.MatchedStars collections are available. The latter is a subset of the Plate.ImageStars property, and contains only those image stars which were used in plate solution.

For example, to solve a plate, write out the precise WCS info, and print the precise centerpoint RA and Dec:

  p.ArcsecPerPixelHoriz = 1.5
  p.ArcsecPerPixelVert = 1.5
  p.RightAscension = p.TargetRightAscension
  p.Declination = p.TargetDeclination
  p.Catalog = 3  ' Corrected GSC
  p.CatalogPath = "C:\GSC-1.1"
  p.Solve
  p.UpdateFITS
  WScript.Echo p.RightAscension & " " & _
               p.Declination
  Next

Where to Go From Here?

The above is only the tip of the iceberg. PinPoint has hundreds of methods and properties that allow you to do a variety of things with FITS images. You can access the image array through PinPoint, create image arrays and attach them, then write out a new FITS file, and much much more. Read through the documentation on the Plate, PlateStars, and PlateStar classes and use your imagination!