Didapi 4 8 1

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
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: aftersales@planmeca.com
DIDAPI 4.8.1
PLANMECA
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
PLANMECA
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
PLANMECA
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
Planmecas 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 everybodys 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
PLANMECA
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
PLANMECA
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
PLANMECA
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
PLANMECA
2012-10-25
Legacy Architecture
DIDAPI 4.8.1
DIDAPI 4.8.1
Page 10(33)
PLANMECA
2012-10-25
DIDAPI 4.8.1
Page 11(33)
Planmecas 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
PLANMECA
2012-10-25
DIDAPI 4.8.1
Current Architecture for Windows and Mac OS X
DIDAPI 4.8.1
Page 12(33)
PLANMECA
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
PLANMECA
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
PLANMECA
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 its 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
PLANMECA
2012-10-25
DIDAPI 4.8.1
Flowchart of Intraoral grabbing
DIDAPI 4.8.1
Page 16(33)
PLANMECA
2012-10-25
DIDAPI 4.8.1
Flowchart of Pan/Ceph Grabbing
DIDAPI 4.8.1
Page 17(33)
PLANMECA
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
PLANMECA
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
PLANMECA
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
PLANMECA
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
PLANMECA
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
PLANMECA
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 nth 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
PLANMECA
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
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
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
PLANMECA
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
PLANMECA
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
PLANMECA
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
PLANMECA
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
Page 28(33)
PLANMECA
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.
DIDAPI 4.8.1
PLANMECA
2012-10-25
DIDAPI 4.8.1
Page 30(33)
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
PLANMECA
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.
DIDAPI_DEV_NOT_PRESENT
Device is no present.
DIDAPI_NOT_INITIALIZED
Error indicates that the application has called at least one DIDAPI function before
the initialisation was ready.
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.
DIDAPI_GRAB_TIMEOUT
Grabbing started normally but failed to complete in time.
Currently not used by the Didapi.
DIDAPI_TRANSFER_ERROR
Transfer from the actual sensor/camera to the computer failed.
DIDAPI_GRAB_NOT_READY
Grabbing has not been initiated.
DIDAPI_GRAB_BUSY
This indicates that the grabbing is still in progress.
DIDAPI_GRAB_DONE
Grabbing has completed successfully.
10
DIDAPI_BAD_PARAM_INDEX
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
PLANMECA
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.
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.
19
DIDAPI_BAD_MODE
Wrong binning (resolution) selected.
20
DIDAPI_BAD_PROG
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
PLANMECA
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

Didapi 4 8 1

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Didapi 4 8 1

Hochgeladen von

Copyright:

Verfügbare Formate

DIDAPI 4.8.

DIDAPI 4.8.1 Interface Standard Specification

The Big Picture

Interfaces, Configuration files and Example applications

Planmeca Implementation of DIDAPI 4.8.1

Current Architecture for Windows and Mac OS X

How to use DIDAPI routines

Inquiring all devices

Before image grabbing

Initializing image grabbing

// OS graphics API call to show the image...

An alternative solution is to call DIDAPI_get_device_status -routine in a Windows timer

Finishing the image grabbing

The image and its parameters

// type double or Unicode String

Flowchart of Intraoral grabbing

Flowchart of Pan/Ceph Grabbing

Version number of the Didapi.dll.

Either detect full configuration, or inquire info from a specific device

String describing the device, for example "Planmeca ProMax

Device's generic type: pan/ceph/intra:

Number of resolution modes supported.

Maximum number of different programs this device supports. Not

The device index to select. This value should be resolved with

Binning resolution mode:

Program mode of Planmeca X-ray device. Not used.

enableCalibration 1 == use calibration, 0 == do not use calibration.

Size of a single pixel in units of 1 m in the horizontal direction.

Size of a single pixel in units of 1 m in the vertical direction (only

Number of digitized bits/pixel.

This routine initialises the grabbing of the image.

The amount of columns (or rows) of the image already grabbed.

Target filename of the image.

If error occurs during the save, returns errno, which depends on

Specifies the format of the image:

Target buffer start position to copy the image to.

This routine fetches a double type parameter.

DIDAPI parameter tag.

This routine fetches UNICODE string type parameter.

DIDAPI parameter tag.

This routine returns the type of the DIDAPI parameter.

This routine sets a double type parameter.

This function sets a parameter of Unicode String type value.

The state of the button.

True (1) if selected, false (0) if unselected.

Other device specific indices are found in header file DIDAPI.h.

Demo Image Grabbing

Configuration File: didapi.ini

Example of the didapi.ini file

Some of the didapi.ini settings explained

Header file result codes

Das könnte Ihnen auch gefallen