DIDAPI 4.8.1 Date: 2012-10-25
PLANMECA Digital Imaging and Applications Division
2012-10-25 Important revision changes: 2012-10-25, Major update 2007-05-03, Pages 16, 25 2006-01-24, Pages 10 2005-09-26, Pages 9, 10 and 24
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
DIDAPI 4.8.1
Page 2(33)
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 3(33)
Planmeca reserves the right to make changes to those specifications without further notice. The information presented in this document has been checked and is known to contain factual errors and omissions. Planmeca disclaims any liability, including without limitation consequential or incidental damages related to the use of the contents of this document. There are no express or implied copyright or patent licenses granted here under to copyrighted material or applicable patents of Planmeca or others. Having said that, we hope the information presented here will be useful and we will proceed in improving both the documentation and the DIDAPI standard it describes, as well as other support material for the DIDAPI interface. All comments and suggestions are highly appreciated -- we hope to establish open and productive relationships with third party software developers as well as other dental imaging device manufacturers. Please send comments etc. to: Email:
[email protected]
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 4(33)
TABLE OF CONTENTS DIDAPI 4.8.1 INTERFACE STANDARD SPECIFICATION.............................................................................. 5 BACKGROUND......................................................................................................................................... 6 THE BIG PICTURE ...................................................................................................................................... 7 Interfaces, Configuration files and Example applications ........................................................ 8 PLANMECA IMPLEMENTATION OF DIDAPI 4.8.1 ...................................................................................... 9 DIDAPI MODEL ......................................................................................................................................... 9 Legacy Architecture ................................................................................................................. 10 Current Architecture for Windows and Mac OS X ................................................................... 12 PROGRAMMING MODEL ....................................................................................................................... 13 HOW TO USE DIDAPI ROUTINES ............................................................................................................. 13 FLOWCHART OF INTRAORAL GRABBING............................................................................................... 16 FLOWCHART OF PAN/CEPH GRABBING................................................................................................ 17 DIDAPI ROUTINES ................................................................................................................................... 18 DIDAPI_initialize .......................................................................................................................... 18 DIDAPI_inquire_devices ............................................................................................................. 18 DIDAPI_select_device ............................................................................................................... 19 DIDAPI_inquire_image ............................................................................................................... 20 DIDAPI_init_grabbing ................................................................................................................. 21 DIDAPI_finish_grabbing ............................................................................................................. 21 DIDAPI_get_device_status ........................................................................................................ 21 DIDAPI_save_image .................................................................................................................. 22 DIDAPI_get_image .................................................................................................................... 23 DIDAPI_get_Dparam ................................................................................................................. 23 DIDAPI_get_Sparam .................................................................................................................. 23 DIDAPI_get_param_type........................................................................................................... 24 DIDAPI_set_Dparam .................................................................................................................. 24 DIDAPI_set_Sparam ................................................................................................................... 24 DIDAPI_get_max_param ........................................................................................................... 24 DIDAPI_get_ready_request ....................................................................................................... 25 DIDAPI_patient_selected .......................................................................................................... 25 DIDAPI_exit ................................................................................................................................. 25 DIDAPI_get_set_params, DEPRECATED .................................................................................... 26 DEMO IMAGE GRABBING ..................................................................................................................... 27 CONFIGURATION FILE: DIDAPI.INI ......................................................................................................... 27 Example of the didapi.ini file..................................................................................................... 28 Some of the didapi.ini settings explained ................................................................................ 29 RESULT CODES........................................................................................................................................ 31 Log File ....................................................................................................................................... 31 Header file result codes............................................................................................................. 31
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 5(33)
DIDAPI 4.8.1 Interface Standard Specification This paper describes the DIDAPI 4.8.1 interface standard. DIDAPI stands for Dental Imaging Device Application Programming Interface. Although it has been defined exclusively by Planmeca Oy (Asentajankatu 6, HELSINKI 00880, FINLAND), it is an open system that we hope will be widely used by third party software developers and dental imaging device manufacturers.
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 6(33)
Background From the beginning, Planmeca recognised the difficulties involved in integrating different digital dental imaging systems and other computerised systems in the dental practice. In Planmeca’s view the customer will expect all the computer-based systems in the practice to be totally integrated or at least work together. This presents many problems to the equipment manufacturer, and it was felt that no global supplier can deliver a totally integrated system that would be adapted to the local (i.e. specific to the country in which the equipment is used) language, culture, legislation and practices. Also, as with any computerised system, the customer will need knowledgeable local support to cope with the maintenance of the system. Rather than trying to create a system that would fit everybody’s every need, it was felt that one workable concept would be, that local software houses in various areas of the globe would integrate the software side of the imaging in their products. In our view this would be in the interest of all the parties: device manufacturers, local software houses, dealers and end users. To achieve this, a common interface between the imaging hardware of various devices (and manufacturers) and the various third party software packages must be defined. To this end DIDAPI was created. Other existing context documents: PMSample&DidapiUISample_4_8_1.pdf Planmeca DidapiUI Interface Model_4_8_1.pdf Planmeca Twain Interface Model_4_8_1.pdf
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 7(33)
The Big Picture DIDAPI is a low level standard for direct control of imaging devices. It has no user interface (obviously the user interface should be “compatible” with the rest of the software system, and thus, no single user interface can meet the case). By using DIDAPI software, developers can integrate the capturing of images into their software. The device manufacturer probably has to provide with the imaging equipment, some additional software having a user interface that can be used to grab, view, store and manipulate images. However, it is anticipated that in the long run, more advanced software will be available from independent software houses in various countries. DIDAPI does not compete with the existing and emerging standards like DICOM 3.0 and INTEGO. Rather DIDAPI can be used by developers to create software links that interface the imaging system with, e.g. hospitals patient management software using above mentioned “higher level” standards. DIDAPI standard defines the interface in the function call level, so that no static linking is necessary; this makes it possible to update the lowest level device control software without touching the rest of the software system.
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 8(33)
Interfaces, Configuration files and Example applications
Planmeca provides integrators Didapi SDK, which contains Didapi SDK interface and Didapi UI interface (see Planmeca DidapiUI Interface Model_4_8_1.pdf). Both interfaces have example programs, PmSample and DidapiUISample. DidapiConfig program is used to configure didapi.dll with didapi.ini file. Didapi prints log to DidapiLog file. DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 9(33)
Planmeca Implementation of DIDAPI 4.8.1 The current implementation consists of low-level device drivers, configuration file(s), calibration file(s) and libraries (DLLs) that provide the functionality as defined by DIDAPI 4.8.1. Also some auxiliary programs are used for configuration and calibration of sensors as explained in paragraph DIDAPI Model. In the current version digital intraoral, pantomographic and cephalometric X-ray devices are supported.
DIDAPI Model Layout of the Planmeca “Legacy” Architecture is shown below (for WIN operating systems). This picture shows how Planmeca hardware has been connected (and in many cases still is) to the PC workstation before Ethernet connection become commonly used. First Didapi checks if there is a configuration file “didapi.ini” (in WINDIR folder) and all other dynamic libraries and necessary calibration files. Then Didapi calls directly or via another dynamic library a device driver, depending on the device type. All other file except configuration files and device driver files (.sys, .inf files) can be or are installed in userdefined folder. Drivers must be and are installed in Windows device folders.
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
Legacy Architecture
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
DIDAPI 4.8.1
Page 10(33)
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 11(33)
Planmeca’s Current Architecture is shown below. These are the devices Planmeca sells currently and how they connect to the Didapi (workstation). It is much alike with the legacy model except connectivity with the Didapi and the Planmeca hardware is done via Ethernet or USB connection. Pan. and Ceph. devices are connected to PC or Mac via Ethernet. No drivers are necessary. Correct IP configuration is needed to establish a connection. Intraoral devices use both Ethernet and USB. ProSensor USB needs “ProSensor_USB.cat” and “ProSensor_USB.inf” -files placed to Windows/inf folder. This matches ProSensor USB device with the chosen the USB driver (usbserial.sys), which is provided by the Microsoft within the Windows operating system. With Mac OS X this is not necessary, no drivers or files are needed. ProSensor Ethernet uses standard POE (Power Over Ethernet) device for powering up the control box and sensor, no drivers are needed. Correct IP configuration is needed to establish a connection. NOTE that all connectivity shown in picture Legacy Architecture is still valid. Customer can still connect his workstation to the Planmeca hardware the way it is shown in that picture, and in many cases customer still does so. NOTE that Didapi will keep buffer of 100 “raw” images per modality in %temp%/images folder. This requires necessary free hard drive space if maximum sensor resolutions are used.
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Current Architecture for Windows and Mac OS X
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
Page 12(33)
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 13(33)
Programming model The programming model consists of an X-ray device with a remote control, a digital camera and an image grabber with enough memory for one full size image. Together these form a logical device. (In practice of course, physical parts of multiple logical devices overlap or are shared e.g. the Pan. and Ceph. devices use the same tube head/generator.) The camera may be line, area or TDI or any other type, that produces image data in the form of a rectangular array of pixels. The image is a rectangular array of pixels address with x and y co-ordinates; the x-axis is parallel to the horizontal direction and the y- co-ordinates increase from top to bottom. In the programming model the device has two parameters that define the size of the image. In this document these parameters are referred to as “mode” and “program”. The idea is that a device may provide various modes (like normal resolution/high resolution) independently of the selected imaging geometry (i.e. program).
How to use DIDAPI routines Most of the functions return as their return value a Didapi code, which is either DIDAPI_OK or an error code. See DIDAPI routines for more detailed explanation. The expected use pattern of the routines is described next.
Initialization At the beginning of the application the initialisation is called once to prepare the DIDAPI library. // initialize DIDAPI interface only once Err = DIDAPI_initialize(...);
Inquiring all devices When the user indicates that an exposure is wanted the system is scanned for devices, to find out which devices are configured at the time. DIDAPI_inquire_devices –routine returns various parameters which can be used to select the correct device index for the device in question. See DIDAPI_inquire_devices for more detailed information. NOTE that DIDAPI_inquire_devices –routine cannot be used to find out if the device in question is really attached to the workstation, it is just configured correctly. NOTE that this is probably the very first point at which the user first considers taking an exposure, so probably this scanning should be done continuously as long as the user has the immediate possibility to initiate an image grabbing procedure. Err = DIDAPI_OK; for(i = 0; Err == DIDAPI_OK; i++) Err = DIDAPI_inquire_devices(...); DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 14(33)
Before image grabbing When the user has the correct device index, device can be selected with the DIDAPI_select_device -routine. After that the program should prepare the X-ray apparatus and image grabber for operation in the selected mode and program with the DIDAPI_set_Dparam -routine. Here in the code snippet the resolution is chosen with the DIDPAI_PTAG_BINNING -didapi tag and dResol value of the binning. The mode, the program and the parameters should be set as selected by the user or, in case of retake, to the same values as used in the original image. Err = DIDAPI_select_device(...); Err = DIDAPI_set_Dparam(DIDAPI_PTAG_BINNING, dResol); NOTE that to support batch mode communication and to simplify implementation (both DIDAPI and the application) this routine will not return until the requested parameters have been set, or an error condition is detected. NOTE that the user has the option to override these setting from the control panel of the Xray device, so the application cannot assume that the X-ray has been set up as requested.
Initializing image grabbing Immediately after that, the system is prepared for grabbing: err = DIDAPI_init_grabbing(...);
Image grabbing During grabbing, the status of the device is polled, to find out how the grabbing is proceeding. If it is required, the application can display the image in real time (preview image) during grabbing by using the scan length returned by the status function, as well as using the DIDAPI_get_image -routine to get the image data. NOTE that preview image may not be supported with all Planmeca devices. NOTE that it is necessary to poll the status via the DIDAPI_get_device_status -routine. // find out image size err = DIDAPI_inquire_image(-1,-1,...); while(DIDAPI_get_device_status(&scanLen) == DIDAPI_GRAB_BUSY) { // To give a turn for device driver in OS scheduler a dummy // function call is added Sleep(100); // Based on the image size, scan length and scan direction // figure out ROI for the data to be displayed here... // get image data err = DIDAPI_get_image(...); }
// OS graphics API call to show the image...
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 15(33)
An alternative solution is to call DIDAPI_get_device_status -routine in a Windows timer function (look at sample project “PmSample”). NOTE that if DIDAPI does not find the calibration file(s) for the chosen sensor, image grabbing cannot proceed (unless image is taken un-calibrated on purpose or with the Dixidevices).
Finishing the image grabbing After grabbing has completed a clean-up, pre-processing and error check must be performed: err = DIDAPI_finish_grabbing(...); Checking for all error value should be done. In some cases, only DIDAPI_finish_grabbing –routine can return error that happened during the image capture. With Pan. and Ceph. devices, if routine returns DIDAPI_IMAGE_UNFINISHED, image grabbing is not over yet. Proceed to the beginning (DIDAPI_init_grabbing -routine) of the image grabbing sequence. See picture Flowchart of Pan/Ceph Grabbing.
The image and it’s parameters At this point the data can be saved to a file using the DIDAPI_save_image -routine (or the data can be fetched using the DIDAPI_get_image -routine and saved by the application in the preferred format, possibly after some compression has been applied to it). The application can also fetch the actual parameters used for the last exposure and save them along with data. nParams = DIDAPI_get_max_param(); nType = DIDAPI_get_param_type(tag); err = DIDAPI_get_Dparam(tag, &dValue); err = DIDAPI_get_Sparam(tag, buffer, length);
// type double or Unicode String // Caller allocated buffer // The length of caller allocated // buffer
err = DIDAPI_save_image(filename...); The sensor resolution is saved in the header of the resulting image file. See following flowcharts of image grabbing processes all together. NOTE that this is recommended way of using Didapi SDK. This is how we use Didapi on our imaging applications. There may be other ways for using Didapi –routines, but in that case it is not supported by Planmeca.
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Flowchart of Intraoral grabbing
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
Page 16(33)
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Flowchart of Pan/Ceph Grabbing
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
Page 17(33)
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 18(33)
DIDAPI routines If the routine is successfully completed, all routines should return DIDAPI_OK (unless otherwise mentioned). If any error or occurs, all routines should return an error code (unless otherwise mentioned). For more information about the return codes, refer to Header file result codes –section or Didapi interface Doxygen documentation. Doxygen generated (html) documentation can be found from the SDK package.
DIDAPI_initialize short DIDAPI_initialize(versno);
// output
This routine initialises the DIDAPI interface. Call this once, and only once, before any other DIDAPI routine. The routine returns, if successful, the software version number of the DIDAPI interface installed on the system. versno
Version number of the Didapi.dll.
DIDAPI_inquire_devices short DIDAPI_inquire_devices( short devIndex, char* typeID, short* devType, short* HWrevision, short* SWrevision, short* maxMode, short* maxProg);
// // // // // // //
input output output output output output output
This routine is used to inquire the devices attached to the computer. Initially “devIndex” should be set to zero. This initializes didapi.dll internal list of all possible devices. After initializing with zero, the “devIndex” should be incremented up, until the correct device is found, or the routine returns “DIDAPI_DEV_NOT_PRESENT”. When the desired device is found, ”devIndex” is used to select this device into use with DIDAPI_select_device -routine. NOTE that DIDAPI_select_device -routine discards all the other devices from the list, except the chosen device. If another index device is needed to be taken into use, the list must be initialized with “devIndex” value zero, and then enumerated again. Information is returned from the routine through the pointer type parameters: devIndex
Either detect full configuration, or inquire info from a specific device 0: Detect all supported devices. > 0: Inquire info of a specified device.
typeID
String describing the device, for example "Planmeca ProMax ProCeph", max length is 31 characters. The text content is not standardized, so it is not recommend to be used e.g. for identifying purposes.
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 19(33)
devType
Device's generic type: pan/ceph/intra: DIDAPI_XRAY_PAN for pantomographic X-ray. DIDAPI_XRAY_CEPH for cephalometric X-ray. DIDAPI_XRAY_INTRA for intraoral X-ray.
HWrevision
A revision number for the device hardware. Currently used only with Dixi ISA.
SWrevision
A revision number for the device software. Currently used only with Dixi ISA.
maxMode
Number of resolution modes supported.
maxProg
Maximum number of different programs this device supports. Not currently used, always == 1.
DIDAPI_select_device short DIDAPI_select_device(short devIndex);
// input
This routine is used to select the device into the use based on the “devIndex” acquired with the DIDAPI_inquire_devices -routine. Blocks until the device is either successfully selected or operation failed. NOTE that when the device is selected with this routine, all the other devices are discarded from the list of possible devices. NOTE that all the rest of the routines apply to the selected device. devIndex
The device index to select. This value should be resolved with DIDAPI_inquire_devices -routine. Unselect currently selected device using devIndex DIDAPI_XRAY_NONE.
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 20(33)
DIDAPI_inquire_image short DIDAPI_inquire_image( short mode, short prog, short enableCalibration, short* imageWidth, short* imageHeight, short* pixelSizeH, short* pixelSizeV, short* pixelDepth, short* scanDir);
// // // // // // // // //
input input input output output output output output output
This routine can be used to inquire the parameters of the image, which will depend on the mode and the program used. Current settings can be enquired with parameter mode = -1. In this case the routine may return the parameters of the image (partially) in memory. Calibration should always be enabled. Calibration depends on the sensor in question, but usually it will compensate imperfections of the sensor. Necessary calibration files should be delivered with the sensor or imaging system installation. If the calibration is disabled, then the image is grabbed without any corrections that are normally done on the data and the image will contain the raw information received from the sensor. NOTE that this routine may be called only before DIDAPI_init_grabbing –routine is called. Violating this rule may or may not cause corruption of the image. mode
Binning resolution mode: 0: Lowest resolution. < 0: Retrieve properties of the current setting.
prog
Program mode of Planmeca X-ray device. Not used.
enableCalibration 1 == use calibration, 0 == do not use calibration. imageWidth
Full image width (number of pixels in the horizontal direction). This is the width of the source image as referred e.g. by DIDAPI_get_image routine.
imageHeight
Full image height (number of pixels in the vertical direction). This is the height of the source image as referred e.g. by DIDAPI_get_image routine.
pixelSizeH
Size of a single pixel in units of 1 µm in the horizontal direction.
pixelSizeV
Size of a single pixel in units of 1 µm in the vertical direction (only square pixel supported).
pixelDepth
Number of digitized bits/pixel.
ScanDir
Indicates the direction of the image scanning, i.e. the order in which the memory is filled during the transfer/grabbing of the image. This is used if a visual real time feedback of the imaging procedure is required. DIDAPI_FM_LEFT: Scan proceeds from X = 0 to right. DIDAPI_FM_RIGHT: Scan proceeds from X = max to left. DIDAPI_FM_TOP: Scan proceeds from Y = 0 to bottom. DIDAPI_FM_BOTTOM: Scan proceeds from Y = max to top.
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 21(33)
DIDAPI_init_grabbing short DIDAPI_init_grabbing(short enableCalibration);
// input
This routine initialises the grabbing of the image. NOTE that the routine returns immediately, but the grabbing will proceed in the background. It usually takes some time to initialize the grabbing. How image grabbing process continues will depend on the device in question. Use DIDAPI_get_device_status routine to inquire the image grabbing status of the device. Calibration should always be enabled. For more information about the calibration, see DIDAPI_inquire_image –routine. enableCalibration 1 == use calibration, 0 == do not use calibration.
DIDAPI_finish_grabbing short DIDAPI_finish_grabbing(); This routine finalizes image grabbing procedure by doing for example calibration, preprocessing, image cropping and marking the image with an orientation letter. NOTE that in some cases, only this routine will return the error code (for example NO_IMAGE_DATA) if some error happened during or after the image capture. This is why it is essential to check the routine return value for possible error condition.
DIDAPI_get_device_status short DIDAPI_get_device_status(short* scanLen);
// output
This routine reports the current status of the image grabbing procedure with the return value. Should be polled using proper interval. Return value DIDAPI_GRAB_NOT_READY tells that device in question is still not ready to capture an exposure. If the return value is DIDAPI_GRAB_BUSY, and variable scanLen is zero, the device is ready for an exposure. The variable scanLen will contain the number of columns (or rows) already grabbed, counting from the edge of the image given by the scanDir-parameter of the DIDAPI_inquire_image -routine. With the return value DIDAPI_OK, routine tells that the image grabbing is finished. Refer to section Header file result codes for complete list of all possible return codes including error codes. scanLen
The amount of columns (or rows) of the image already grabbed.
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 22(33)
DIDAPI_save_image short DIDAPI_save_image( char* filename, short* OSerror, short format);
// input // input // input
This routine saves the image to the file in a requested format. The sensor resolution is saved in the header of resulting image TIF -file. NOTE that 8-bit images are always clipped (from histogram) 0.5% from both ends to increase contrast. 16-bit images are as processed. NOTE that non-calibrated images may be useless if saved to 8bit. filename
Target filename of the image.
OSerror
If error occurs during the save, returns errno, which depends on operating system.
format
Specifies the format of the image: DIDAPI_RAW: Image is saved in 12 bits/pixel by saving each pixel directly to the file as 16 bit integer. DIDAPI_RAW8B: Image is saved in 8 bits/pixel by saving each pixel directly to the file as 16 bit integer. DIDAPI_TIFF: Image is saved in 8bits/pixel using 8bit TIFF format. DIDAPI_TIFF16B: Image is saved in 12 bits/pixel using 16bit TIFF format. DIDAPI_JPEG_8: Image is saved in 8bits/pixel using 8bit JPEG format. DIDAPI_JPEG_12: Image is saved in 12 bits/pixel using 16bit JPEG format.
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 23(33)
DIDAPI_get_image short DIDAPI_get_image( unsigned char* buffer, short depth, short skipFactor, short x0, short y0, short w, short h);
// // // // // // //
input input input input input input input
This routine copies the pixel data from the image memory to the provided buffer. The format of the data in the buffer is the same as if the buffer had been filled with the same data from a raw data file; see description of DIDAPI_save_image -routine. buffer depth skipFactor x0, y0 w, h
Target buffer start position to copy the image to. The image depth, 8 bit or 16 bit. Skip every n’th line and row when copying into the target. 1 means the whole image. First source column or row index. Index zero indicates the first grabbed column or row. The direction of the grabbing depends on the device type (see DIDAPI_inquire_image –routine scanDir). Width and height of the target image buffer.
DIDAPI_get_Dparam short DIDAPI_get_Dparam( long tag, double *dValue);
// input // output
This routine fetches a double type parameter. tag dValue
DIDAPI parameter tag. (See “DIDAPI.h Parameter tags” for all possible parameter tags.) The exposure- or Planmeca device parameter value of type double.
DIDAPI_get_Sparam short DIDAPI_get_Sparam( long tag, wchar_t *buffer, int length);
// input // output // input
This routine fetches UNICODE string type parameter. NOTE that wchar-type length depends on the operation system used. tag buffer length
DIDAPI parameter tag. (See “DIDAPI.h Parameter tags” for all possible parameter tags.) Caller allocated buffer for returned UNIOCDE parameter. The length (in chars) of caller allocated buffer.
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 24(33)
DIDAPI_get_param_type int DIDAPI_get_param_type(long tag);
// input
This routine returns the type of the DIDAPI parameter. NOTE that unlike most of the Didapi SDK routines, this one returns the type, not “DIDAPI_OK” if successful. The types are: DIDAPI_VALUE_TYPE_DOUBLE DIDAPI_VALUE_TYPE_UNICODE_STRING DIDAPI_VALUE_TYPE_NOT_DEFINED. tag
DIDAPI parameter tag. (See “DIDAPI.h Parameter tags” for all possible parameter tags.)
DIDAPI_set_Dparam short DIDAPI_set_Dparam( long tag, double dValue);
// input // input
This routine sets a double type parameter. tag dValue
DIDAPI parameter tag. (See “DIDAPI.h Parameter tags” for all possible parameter tags.) Double type value to be set.
DIDAPI_set_Sparam short DIDAPI_set_Sparam( long tag, wchar_t *szValue, int length);
// input // input // input
This function sets a parameter of Unicode String type value. NOTE that wchar-type length depends on the operation system used. tag szValue length
DIDAPI parameter tag. (See “DIDAPI.h Parameter tags” for all possible parameter tags.) UNICODE character string buffer. The length of the buffer (in chars).
DIDAPI_get_max_param int DIDAPI_get_max_param(); This function returns the maximum number of DIDAPI parameters tag. NOTE that unlike most of the Didapi SDK routines, this one returns integer number, not “DIDAPI_OK” if successful.
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 25(33)
DIDAPI_get_ready_request short DIDAPI_get_ready_request(short *flag);
// output
This routine reads the ready button state from the device. This is meaningful only with Dimax1 sensor in ProLine device that is connected to PC via PCI card. flag
The state of the button.
DIDAPI_patient_selected short DIDAPI_patient_selected(short flag);
// input
This routine sends information to the PM device that the PC is in ready state. Pan and Ceph devices need this information. NOTE that this is meaningful routine only with ProLine device (with Dimax3 sensor). flag
True (1) if selected, false (0) if unselected.
DIDAPI_exit void DIDAPI_exit(); Use this routine to clean up after the use of Didapi.dll.
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 26(33)
DIDAPI_get_set_params, DEPRECATED short DIDAPI_get_set_params( short operation, short* paramData); This routine is used to get and set the parameters of the X-ray device. Because this involves communication with the X-ray (possibly through relatively low band width channel) this routine may take some time to complete. In some cases, a separate “synchronisation cable” from Planmeca is needed for this channel. The possible values for “operation” are as follows: DIDAPI_INQUIRE_PARAM: Get information about the parameters. DIDAPI_GET_PARAM: Get the parameters. DIDAPI_SET_PARAM: Set the parameters. DIDAPI_LAST_PARAM: Used to return the actual values used in the last exposure. The following standard parameter numbers have been assigned: Index 0 1 2 3 4 5
Contents Parameter numbers in this device Device mode index. (Binning resolution) The DPI value is saved in header of result TIF file. (Device program index) Not used anymore Tube voltage kV Tube current mA Exposure time (sec x 1000)
Other device specific indices are found in header file “DIDAPI.h”. NOTE that ProMax device does not return all parameter values.
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 27(33)
Demo Image Grabbing Didapi.dll library has a demo image priority for a selected device over a real Planmeca device driver. It looks for the demo image as specified below from the same folder where Didapi.dll is installed. If the demo image is not found, then Didapi.dll operates as usual. This feature allows development without a real Planmeca device. NOTE that DIDAPI_get_device_status -routine returns scanLen value, but not when real Dixi2 sensor used. The images must be grey scale TIF images formatted to 8-bit or 16-bit (scaled to 12-bit level). The naming of images is fixed. Following naming rule must be followed: Intraoral image Panoramic image Cephalometric image
“db_image_intra0.tif” “db_image_pan0.tif” “db_image_ceph0.tif”
Acceptable images can be found in “Tools/demo image” folder on installation disc or with the SDK package.
Configuration File: didapi.ini End user needs to configure didapi.dll depending on which device he may use and what kind of preferences he has, for example image processing as well as various other configurable properties. To achieve this end user launches DidapiConfig.exe program to make these changes to didapi configuration file “didapi.ini”, that exists in the Windows – folder (%WINDIR%). The file is plain text ASCII formatted and can be edited with any text editor. There is a separate section in the INI file for each device (e.g. DIMAX2_P for Dimax2 – Dimax4 panoramic). See example and description of the most important sections and settings below. NOTE that didapi.ini is a mandatory file for didapi.dll operation. DidapiConfig is not mandatory, but we recommend it to be used to make changes to didapi.ini.
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Example of the didapi.ini file [DIMAX2_P] AutoLevelsEnabled=1 ClipLowPct=0.100 ClipHighPct=0.100 Gamma=0.30 UseLogarithm=1 SelectedSCurve=12 NoSCurves=15 UseFactorAboveMM=9 Factor=0.35 UsePepperMedian=1 LogFilter=1 [DIMAX2_B] AutoLevelsEnabled=1 ClipLowPct=0.100 ClipHighPct=0.100 Gamma=0.25 UseLogarithm=1 SelectedSCurve=12 NoSCurves=15 UseFactorAboveMM=9 Factor=0.35 UsePepperMedian=1 LogFilter=1 [DIMAX2_T] AutoLevelsEnabled=1 ClipLowPct=0.100 ClipHighPct=0.100 Gamma=0.25 UseLogarithm=1 SelectedSCurve=1 NoSCurves=15 UseFactorAboveMM=9 Factor=0.35 UsePepperMedian=1 LogFilter=1 …
See the full list of the settings from the latest didapi.ini configuration file.
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
Page 28(33)
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 29(33)
Some of the didapi.ini settings explained [PROSENSOR] AutoLevelsEnabled=1 Enable = 1, disable = 0. Performs an autolevel function and should adjust the image to the optimal settings. ClipLowPct=0.000 Used if AutoLevels is enabled. Defines how many per cent of the bright (low signal in non-inverted image) pixels gets maximum value. ClipHighPct=0.100 Used if AutoLevels is enabled. Defines how many per cent of the dark (high signal in non-inverted image) pixels gets minimum value. Gamma=0.60 Used if AutoLevels is enabled. A gamma function to modify grey scale values. Fmh=0 Enable = 1, disable = 0. Noise removal filtering used with Dixi < V3 sensors. UseLogarithm=0 Enable = 1, disable = 0. Logarithmic image processing that affects the grey values. Log function is developed for panoramic and works mostly for intra too. LogFilter=0 Enable = 1, disable = 0. DICE processing. Filters noise and increases contrast. PSeUseMedian=1 Enable = 1, disable = 0. Median filtering NoSCurves=6 Used with UseLogarithm. Defines how many s-curves are defined. SelectedSCurve=5 Used with UseLogarithm. Selects S-curve. AutoExpThresholdS0=50 Size 0 triggering threshold. If trigger problems, this can be lowered down to 20 before self-triggering. AutoExpThresholdS1=50 Size 1 triggering threshold. If trigger problems, this can be lowered down to 20 DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 30(33)
before self-triggering. AutoExpThresholdS2=50 Size 2 triggering threshold. If trigger problems, this can be lowered down to 20 before self-triggering. UseFactorAboveMM=3 Used by DICE. Not recommended to modify. Factor=0.35 Used by DICE. Not recommended to modify. UsePepperMedian=0 Enable = 1, disable = 0. Pepper noise filtering Image4BBoundary=0 Makes number of columns/rows dividable by 4 PlanetConnected=0 Enable = 1, disable = 0. Enable when Planet cable (for acquiring Planmeca Intra x-ray exposure parameters) is connected. ExposureTime=400 Calibration parameter that defines the length of the dark image exposure time in milliseconds. [DIMAX2_C] Ceph. related options (normally not defined) ShowAll=0 Valid values are 0 and 1. 0 enables cropping from left/right so that image is clean rectangle. 1 disables cropping of any exposured area. Image will have uneven left and right sides.
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 31(33)
Result codes Log File For debugging purpose DIDAPI calling sequences are written into “didapi.log” file. Log file is stored in %temp% folder. Content is stored using FIFO (First in, first out) principle and the maximum size of file is limited to about 1.4 MB. In “DidapiConfig.exe” there is a DidapiLog “Full/Debug” setting, which should be enabled for debugging purposes. This enables more detailed log prints from the Didapi.dll.
Header file result codes The most fresh result codes are found in ‘DIDAPI.h’ header file. 1
DIDAPI_OK Routine completed normally, requested operation performed/initiated.
2
DIDAPI_DEV_NOT_PRESENT Device is no present.
3
DIDAPI_NOT_INITIALIZED Error indicates that the application has called at least one DIDAPI function before the initialisation was ready.
4
DIDAPI_OS_ERROR Operating system error caused abnormal abortion of the requested operation. This error is reported by routines that access the operating system for file access service and DeviceIOControl. In case of this error, the actual OS error is returned through the parameter “Oserror” of the routine that returned this error.
5
DIDAPI_GRAB_TIMEOUT Grabbing started normally but failed to complete in time. Currently not used by the Didapi.
6
DIDAPI_TRANSFER_ERROR Transfer from the actual sensor/camera to the computer failed.
7
DIDAPI_GRAB_NOT_READY Grabbing has not been initiated.
8
DIDAPI_GRAB_BUSY This indicates that the grabbing is still in progress.
9
DIDAPI_GRAB_DONE Grabbing has completed successfully. Currently not used by the Didapi.
10
DIDAPI_BAD_PARAM_INDEX Currently not used by the Didapi.
100
DIDAPI_BAD_PARAM_VALUE The requested parameter for the X-ray associated with the device, could not be set to the requested value.
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 32(33)
12
DIDAPI_BAD_PARAM_OPERATION The requested operation cannot be performed, on the requested parameter for the X-ray associated with the device.
13
DIDAPI_ROI_OUT_OF_BOUNDS The requested image area exceeds the size of the image in memory. Currently not used by the Didapi.
14
DIDAPI_DEV_NOT_CALIBRATED The device has not been calibrated (for this mode) or calibration file is for wrong sensor.
15
DIDAPI_CALIB_FAILURE The device calibration failed.
16
DIDAPI_FILE_NOT_OPENED Open error of image file.
17
DIDAPI_FILE_WRITE_FAILURE Failed to save a file to destination.
18
DIDAPI_HW_NOT_PRESENT Physical card is not present. Currently not used by the Didapi.
19
DIDAPI_BAD_MODE Wrong binning (resolution) selected.
20
DIDAPI_BAD_PROG Currently not used by the Didapi.
21 DIDAPI_IMAGE_UNFINISHED Error condition for DIDAPI_finish_grabbing –routine. Routine returns, but for some reason image grabbing failed or is still in progress. 22
DIDAPI_OUT_OF_MEMORY Run out of memory while allocating buffers.
23
DIDAPI_MISSING_TEMP_DIR Working directory or path to the log file cannot be resolved.
24
DIDAPI_NO_IMAGE_DATA Image data is missing, image may be lost.
25
DIDAPI_WARNING_OLD_CAL_FILE Calibration files are old. This version of DIDAPI contains a new calibration procedure for this sensor. The sensor must be re-calibrated (for this mode).
26
DIDAPI_INCORRECT_PASSWORD This is used with the Ethernet devices.
27
DIDAPI_PAN_SENSOR_NOT_CONNECTED Panoramic sensor is not connected
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
PLANMECA Digital Imaging and Applications Division
2012-10-25
DIDAPI 4.8.1
Page 33(33)
28
DIDAPI_CEPH_SENSOR_NOT_CONNECTED Cephalometric sensor is not connected
29
DIDAPI_XRAY_BUSY X-ray might be in use. If not, try rebooting it.
30
DIDAPI_PC_COMM_DISABLED_IN_XRAY PC communication is disabled in X-Ray
31
DIDAPI_UNABLE_TO_RESOLVE_HOST_NAME Unable to resolve a host name for the Ethernet interface. Please check the settings with the DidapiConfig.
32
DIDAPI_UNABLE_TO_MAKE_TCP_CONNECTION Unable to make a TCP connection to the sensor.
33
DIDAPI_CONNECTION_TO_SENSOR_IS_BAD Connection to sensor seems to be bad for transferring data.
34
DIDAPI_BUFFER_TOO_SMALL_PARAMS Given buffer is too small for parameters.
35
DIDAPI_BUFFER_TOO_SMALL_STRINGDATA Given buffer is too small for string type of data.
36
DIDAPI_VALUE_NOT_AVAILABLE Tag value is not found for the device.
37
DIDAPI_CANNOT_SET_PARAMETER Tag value cannot be set for the device
38
DIDAPI_DEVICE_NOT_SELECTED Device is not selected with DIDAPI_select_device –routine.
39
DIDAPI_INVALID_PARAMETER_VALUE Tag value greater than available
40
DIDAPI_X_RAY_NOT_WORKING_PROPERLY Problems to communicate with the sensor or power failure
41
DIDAPI_REMOVE_3D_SENSOR 3D sensor is attached but 2D exposure is selected.
42
DIDAPI_TOO_OLD_DEVICE_SW Device software version is too old.
43
DIDAPI_NOT_AVAILABLE Routine that returns this is not supported for selected device.
44
DIDAPI_INTERNAL_ERROR Something unexpected happened.
DIDAPI 4.8.1 Copyright © 1995-2012 Planmeca
