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
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.
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.
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.
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.
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.. |
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:
|
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:
|
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 |
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.
2018/07/14 Support of 64 bits for Astroart 7. Version 7.0