Astroart plug-in SDK 7 (software development kit)

This document explains how to create compatible plug-ins for Astroart 7.0/6.0/5.0.


1.1) Introduction

1.2) Requirements

1.3) New features

2.1) Let's start

2.2) Exported functions

2.3) Types & commands

3.1) Technical support

3.2) History


Introduction

A "plug-in" is an external module (DLL) that extends an application. For a software like Astroart, plug-ins may be related to image filters, camera control, file management or astronomical calculations.

Requirements

Since Astroart plug-ins are standard DLLs, any compiler can be used for this purpose. This SDK contains some examples in C++ and Pascal (Visual Studio 2008, CodeBlocks 13 GCC, C++ Builder 3, Delphi 5, Lazarus 1). Although almost every programming language allows creation of DLLs, this is often an uncommon task for most programmers; we recommend to take a look at the specific documentation of your compiler.

Let's start

This document provide complete documentation for programmers of C++ and Pascal. The fastest way to start is to take a look and compile the demos included in this archive.
Astroart looks for plug ins when it starts; for every plug-in correctly recognized there will be a new Menu command in the Tools submenu. There is no need to "install" plug-ins, every DLL placed in the Astroart directory will be checked and installed if its name is compatible with the following convention:

32 bit: PI*.DLL , where "*" means a sequence of characters.

64 bit: P64I*.DLL , where "*" means a sequence of characters.

Example of valid plug-in names: PIFFT.CCD , PIGAUSS.DLL , P64IFFT.DLL , P64IGAUSS.DLL ..

This means that installing plug-ins in Astroart is very easy for final users: simply copy them into the installation directory. Software authors may implement this automatically in a installation wizard.

Exported functions

A DLL (dynamic link library) is a collection of functions which are exported to applications which use that DLL. Astroart needs three functions from a valid plug-in:

pi_initialize, pi_activate, pi_finalize.

Example of C declaration:

int WINAPI pi_initialize(void *funcaddress, char *menuname, char *description, HWND whandle)

void WINAPI pi_activate(void *pimage, HWND whandle)

void WINAPI pi_finalize(HWND whandle)

Pascal declaration:

function pi_initialize(funcaddress:pointer; menuname,description:pansichar; whandle: HWND):integer; stdcall;

procedure pi_activate(pimage:pointer; whandle:HWND); stdcall;

procedure pi_finalize(whandle:HWND); stdcall;

Generic declaration:

pi_initialize (int32/64, int32/64, int32/64, int32/64) -> int32 (EAX)

pi_activate (int32/64, int32/64)

pi_finalize (int32/64)

Note the calling convention for 32 bit: WINAPI (= STDCALL) this is the standard for Windows.
The C declaration uses void* to indicate generic pointers; this can be safely changed.

pi_initialize

this functions is called when Astroart starts and looks for plug-ins. menuname and description are pointers to buffers where the function should write the following strings (null terminated): menuname: the name on the main menu of Astroart. description: the hint which appears on the status bar of Astroart.

Example (C):

strcpy(menuname,"CCD Control")
strcpy(description,"A CCD plug-in for xyz cameras from Z software")

whandle is the Window Handle of the Astroart main window, it can be ignored. funcaddress is a pointer to a special function of Astroart; it must be stored in a global variable for future use, see types & commands. This function must return a non-zero value if it executes correctly.

pi_activate

this function is called when the user clicks the Menu related to the plug-in.

pimage is the pointer of the current active image, see types & commands.

whandle is the Windows handle of the active MDI Child window.

When pi_activate is called the plug-in should perform its task: for example a filter should elaborate the active image. If instead the plug-in has a User Interface then it should display its dialog window; for example a panel for CCD control.

pi_finalize

this functions is called when Astroart is going to quit. You may use it to deallocate memory or handlers.

Types and commands

There are two special types that a plug-in must use when interfacing with Astroart: pointer to image and pointer to callback, both can be represented with a 32 bit variable, we will call them pimage and pcallback.

pimage is a pointer to a special structure which represent an image. The plug-in does not need to know how it is organized.

pcallback is a pointer to a special function of Astroart which the plug-in can call to perform its tasks. This is called a "call-back" function, since it is called by the plug-in while other functions (like pi_activate) are called by Astroart.
IMPORTANT: if the plug-in uses threads for background processing they cannot call the callback function. When the background process is terminated they must be syncronized with the main thread and only the main thread should call the callback function, for example to update the image.

The call-back function

Example of C declaration:

typedef int/int64 WINAPI (*Tcallbackfunc) (Tcommand, void*, void*, void*);

Pascal declaration:

Tcallbackfunc = function(command:Tcommand; p1,p2,p3:pointer):nativeint; stdcall;

Generic declaration:

CallbackfuncType = pointer to function (int32, int32/64, int32/64, int32/64) -> int32/64

The callback function takes four parameters: the first is the command (example: "Create an image"), the others are parameters. Example: myimage = callback(ac_create,400,300,0) will create a new (gray tone) image into Astroart with width = 400 pixels and height = 300, and it will return a pointer to new image for further elaborations.

Commands

enum AstroartCommand {ac_getbuffer, ac_getsize, ac_redraw, ac_close, ac_savefits, ac_copy, ac_writeheader, ac_readheader, prepareundo, ac_thresholds, ac_transferfunc, ac_getselpoint, ac_getselpoint2, ac_gethwnd, ac_create, ac_open, ac_getimage, ac_getversion, ac_rename, ac_getname, ac_getra, ac_getdec, ac_getx, ac_gety, ac_modified, ac_blink, ac_flip, ac_resize, ac_findcoordinates, ac_reserved_1, ac_selectpoint, ac_selectrect, ac_reserved_2, ac_reserved_3, ac_reserved_4, ac_centeratlas};

NAME

PARAMS TYPE and COMMENT

RETURNS

ac_getbuffer

pimage, &buffer, colorplane

This function gets a pointer to the buffer where the image is stored (32 bit floating point data) and returns 2 if there are no errors. This a fundamental function to modify the image (for example to make filters). If the image has colors then the colorplane parameter specifies the green, red, or blue color plane (R = 2, B = 3, else G).

0,2

ac_getsize

pimage, &x, &y

This function gets in X and Y the width and height of pimage. This is usually required before using ac_getbuffer, to calculate the size of the image (X*Y*2). If the function return zero then pimage is an invalid pointer.

0,1

ac_redraw

pimage, calcstats, autovis

Redraws pimage. This is required after you have modified the image buffer. If calcstats is 1 the Astroart will recalculate the image statistics (recommended), if autovis is 1 then the image will be displayed with a new visualization automatically calculated.

0,1

ac_close

pimage, askuser, NULL

Closes pimage. If askuser is 1 and the image was modified then a dialog window will ask confirmation to the user.

0,1

ac_savefits

pimage, pfilename, NULL

Saves pimage as a FITS file. Pfilename is the pointer to a null-terminated string of the file name.

0,1

ac_copy

pimage, NULL, NULL

Copies pimage into the clipboard.

0,1

ac_writeheader

pimage, Pheader, NULL

Writes the FITS header of the image from the null-terminated string pheader. If the header contains WCS keywords they will be used for astrometry calibration. Every row of the header must be separated by carriage returns and there is no need for trailing spaces.

0,1

ac_readheader

pimage, NULL, NULL

Gets the pointer to a null-terminated string representing the FITS header. Every row is separated by carriage returns, this string is read-only.

Pheader

ac_prepareundo

pimage, NULL, NULL

Copies the image into an internal Undo buffer. This allows the users to undo the operations of the plug-in.

0,1

ac_thresholds

pimage, min, max

Sets the minimum and maximum visualization thresholds of the image. Use ac_redraw to update the image.

0,1

ac_transferfunc

pimage, trf, NULL

Sets the transfer function of the image. Use ac_redraw to update the image. The valid range is [-20..20] , -20 logarithmic, +20 exponential, 0 linear.

0,1

ac_getselpoint

pimage, &x, &y

Gets the coordinates of the selected point of the image.

0,1

ac_getselpoint2

pimage, &x, &y

Gets the coordinates of the second selected point of the image, if a rectangular region is selected over the image. If x and y contain the constant 10001H then the function returns the number of point selected over the image. If only x contains such constant then the function gets the coordinates of the y# point of the image, (0 to N-1).

0,1

ac_gethwnd

pimage, NULL, NULL

Gets the Window Handle of the active MDI Child window.

HWND

ac_create

x, y, color

Creates a new image with witdh = x and height = y. If color is not zero then a color image will be created.

pimage

ac_open

pfilename, NULL, NULL

Opens an image from disk. Pfilename is null-terminated string. If a I/O error occours it returns NULL.

pimage

ac_getimage

selection, NULL, NULL

If selection is PACTIVEIMAGE it returns the active image, if selection is PSELECTIMAGE a dialog window will ask the user to select an image (unless there is only one image in Astroart)

pimage

ac_getversion

NULL, NULL, NULL

Returns the version of the plug-in subsystem. This value is 502 for Astroart 5.0 SP2.

400+

ac_rename

pimage, pname, keeppath

Renames the image. If path = 1 then the original path of the filename will not be changed.

0,1

ac_getname

pimage, path, NULL

Gets the filename of the image. If path = 1 returns the name and the complete path in the file system.

pname

ac_getra

pimage, x*100, y*100

Returns the R.A. of the pixel at coordinates X,Y for images with astrometric calibration. X and Y are intended in hundredths of pixels. The result is an integer number as degrees*100000.

0..360E5

ac_getdec

pimage, x*100, y*100

Returns the DEC. of the pixel at coordinates X,Y for images with astrometric calibration. X and Y are intended in hundredths of pixels. The result is an integer number as degrees*100000.

-90E5..
90E5

ac_getx

pimage, RA*1E6, DEC*1E6

Given the coordinates RA and DEC (multiplied by 1000000) returns the pixel X coordinate for images with astrometric calibration. The result is an integer number as hundredths of pixel.

X*100

ac_gety

pimage, RA*1E6, DEC*1E6

Returns the pixel Y coordinate for images with astrometric calibration. The result is an integer number as hundredths of pixel.

Y*100

ac_modified

pimage, modified, NULL

Sets the modified flag of the image. When an image is marked as modified, it cannot be closed directly (a dialog window asks to save the changes).

0,1

ac_blink

NULL , NULL , NULL

If two images are opened inside Astroart, they are blinked.

0,1

ac_flip

pimage, axis, NULL

Flips the image. Axis 1 = horizontal, 2 = vertical, 3 = both.

0,1

ac_resize

pimage, dimX, dimY

Resizes the image.

0,1

ac_findcoordinates

pimage, pparameters, NULL

Performs plate solving on the image. A pointer to the following structure must be passed:
struct {float imgFovX, float sizeErrorPerc, float maxAngle, float approxRa, float approxDe, float searchRa, float searchDe, float minStars, int isFlipped}.
if you set imgFovX = 0.0 (recommended) then imgFovX, sizeErrorPerc and maxAngle will be get from the Astroart preferences (Find Coordinate window). If you set searchRa = 0.0 then a default rectangle of 2 x 2 degrees will be used for searching.

0,1

ac_selectpoint

pimage, X, Y

Selects on the image the point at coordinates X,Y.

0,1

ac_selectrect

pimage, prect, NULL

Selects on the image a rectangle. A pointer to the following structure must be passed:
struct {int x1, int y1, int x2, int y2}.

0,1

ac_centeratlas

RA*1E6, DEC*1E6, showAtlas

Centers the star atlas to the given coordinates. If the atlas is currently not opened you can open it with the flag showAtlas = 1.

1

Technical support

MSB software encourages Windows programmers to write plug-ins; both freeware and commercial plug-ins will be listed in our web site for free. Complete technical support is given to developers of C/C++, Pascal, Delphi and PowerBasic but we will give help and suggestions also for other languages.

History

2018/07/14 Support of 64 bits for Astroart 7.   Version 7.0
2017/11/26 Updated version for Astroart 6.   Version 6.0
2013/12/28 First version for Astroart 5.   Version 5.0