Hamamatsu Photonics K.K.(it is described as the following HPK) has copyright of this document and the software sample codes. This document is included in DCIMG-SDK. Developer who uses DCIMG-API in their custom software can refer this.

This document and the software sample codes are disclosed only for the purpose described above, and do not constitute a license, transfer, or any other entitlement for the owner.

All of risk and result of using software depending on this document remains with the user.

This document may include technical inaccuracies or typographical errors. HPK does not guarantee any damage arising from such errors or this document.

HPK makes no commitment to update or keep current the information contained in this document.

All brand and product names are trademarks or registered trademarks of their respective owners. HPK has copyright of this document with all rights reserved.

No part of this documentation may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language or computer language, in any form, or by any means, in any means, electronic, mechanical, magnetic, optical, chemical, manual or otherwise, without the prior written permission of HPK.

DCIMG-API is an application software program interface to read files which are recorded by DCAM-API recording functions, hereafter referred to simply as “DCIMG file”). DCAM-API is application software program interface to control preparing digital cameras and detecting system manufactured by HAMAMATSU (hereafter referred to simply as “devices”). DCIMG-API is installed when DCAM-API is installed. DCAM-API itself is downloadable from website, www.dcamapi.com.

The DCIMG software development kit (hereafter referred to as the “SDK”) gives resource for making host software program by their developer.

The SDK consists of header files, library files, reference files of DCIMG-API functions, and source code of sample application software to give knowledge how to access DCIMG-API. SDK users are free to use the software in any way they like, such as partially modifying source codes and creating completely separate program, and also giving application software or plugin module for everyone. But followings are not allowed; opening the resources that get from HAMAMMATSU as SDK; making very thin wrapper module that is almost same as DCIMG-API itself.

Concept of DCIMG-API is to give easy access to DCIMG files. HPK does not open file format itself but gives API for accessing these files because DCIMG file format may be expanded when DCAM-API supports new function. So supporting by DCIMG-API is easier for developer than opening DCIMG file format. Basically functions are for reading file into PC memory, there is no function for displaying and GUI control. Therefore the number of functions has been limited to the minimum. For common use, format of calling function are defined in the C programming language.

HDCIMG is the handle which specifies the target file on DCIMG-API. Almost DCIMG-API functions use this handle as a parameter. dcimg_open() function returns this handle to host software, and dcimg_close() function releases it at terminating using the device.

All DCIMG-API functions are contained by small letters and they start by "dcimg_".

All function except dcimg_init() function and dcimg_open() function, the first arguments are always HDCIMG handle. Some functions need additional argument and if there are 3 parameters or more, structure is used. In case of structure parameter, function requires a pointer and the first member of the structure indicates a size of the structure. If you do not have any option for other members, please fill them with 0.

All function returns value of DCIMG_ERR. All values are defined with DCIMG_ERR_ prefix. If function successes DCIMG_ERR_SUCCESS is return value.

The smallest content of DCIMG file is "Frame". Frame is 2D image. The series of contiguous capturing images is called as "Session". The first frame in session is beginning capturing or resuming recording. The last frame is the last before stopping capturing or pausing recording. DCIMG file can contain multiple session.

At starting using DCIMG-API, host software needs to call dcimg_init() function first, then call dcimg_open() function to get HDCIMG handle.

To release HDCIMG handle at ending using the file, host software needs to call dcimg_close() function. There is no ending function for DCIMG-API itself.

Almost DCIMG-API functions require a HDCIMG handle. The HDCIMG handle is used for specifying the DCIMG file that the host software controls and it is got by dcimg_open() function.

An easy way to access image data is calling dcimg_lockframe() function. First preparing instance of structure DCIMG_FRAME, second setting size member and iFrame member, then call this function to get the image information and point to access image data.

dcimg_copyframe() function is used to copy image data into user prepared buffer. Before calling this function, the host software has to fill necessary member of structure DCIMG_FRAME. The function dcimg_getparaml() is prepared to get some information, e.g. image size, pixeltype and so on.

DCIMG file includes not only image data but also other data, which is called "metadata". The function dcimg_copymetadata() can return single metadata of a frame. The function dcimg_copymetadatablock() can return metadata across multiple frames.

Frame index in DCIMG-API is 0 based. The index of first frame in a session is 0.

In DCIMG-API, from starting record to finishing is called session. DCIMG file can include multiple sessions. dcimg_setsessionindex() function can change current session by session index. dcimg_getsessionindex() function can return current session index. Session index is 0 base. The first session index is 0.

dcimg_getparaml() function can return various parameter in DCIMG file. enum DCIMG_IDPARAML can specify which parameter host software wants to know.

DCIMG_ERR dcimg_init( DCIMG_INIT* param );

dcimg_init() function initializes DCIMG-API runtime. Host software calls this function before calling other functions.

DCIMG_ERR dcimg_open( DCIMG_OPEN* param );

dcimg_open() function opens the DCIMG file specified by member path of the structure DCIMG_OPEN and return HDCIMG handle. Host software calls this function to get HDCIMG handle. If host software does not need the HDCIMG handle any more, it should call dcimg_close() function. After calling dcimg_close() function, HDCIMG handle is not available and host software can call dcaimg_open() function to get HDCIMG handle again. If this function can open the file, this function returns DCIMG_ERR_SUCCESS and the member hdcimg of the structure DCIMG_OPEN return the HDCIMG handle of specified file. If DCIMG-API could not open the specified file, this function returns error code.

DCIMG_ERR dcimg_close( HDCIMG hdcimg );

dcimg_close() function release HDCIMG handle and the DCIMG file. After calling this function and success, the HDCIMG handle is not available. To use same DCIMG file again, host software has to call dcimg_open() function for getting HDCIMG handle.

DCIMG_ERR dcimg_getdata( HDCIMG hdcimg, DCIMGDATA_HDR* hdr );

dcimg_getdata() function gets the data that it is impossible to get with paraml. The structure is prepared by the kind of data. These structures have DCIMGDATA_HDR as the first member.

DCIMG_ERR dcimg_lockframe( HDCIMG hdcimg, DCIMG_FRAME* pFrame );

dcimg_lockframe() function returns a pointer that host software can use to access an image data in DCIMG file. Next calling this function will prepare new data, so the DCIMG_FRAME parameter which was filled by last call is no more available. If the image frame which is specified by DCIMG_FRAME::iFrame is not exist, dcimg_lockframe() function will return DCIMG_ERR_INVALIDFRAMEINDEX. To avoid this situation, host software get the number of frame in session to call dcimg_getparaml() with DCIMG_IDPARAML_NUMBEROF_FRAME.

DCIMG_ERR dcimg_copyframe( HDCIMG hdcimg, DCIMG_FRAME* pFrame );

dcimg_copyframe() function copies image data from DCIMG file to specified buffer that host software gives

DCIMG_ERR dcimg_copymetadata( HDCIMG hdcimg, DCIMG_METADATAHDR* hdr );

dcimg_copymetadata() function copies meta data from DCIMG file to specified buffer that host software gives.

DCIMG_ERR dcimg_copymetadatablock( HDCIMG hdcimg, DCIMG_METADATAHDR* hdr );

dcimg_copymetadatablock() function copies plural meta data from DCIMG file to specified buffer that host software gives. Available kinds of meta data are TIMESTAMP and FRAMESTAMP.

DCIMG_ERR dcimg_setsessionindex( HDCIMG hdcimg, int32 index );

dcimg_setsessionindex() function changes the target session when DCIMG file has some session. The session index is 0 based.

DCIMG_ERR dcimg_getsessionindex( HDCIMG hdcimg, int32* pIndex );

dcimg_getsessionindex() function returns the target session index. The session index is 0 based.

DCIMG_ERR dcimg_getparaml( HDCIMG hdcimg, DCIMG_IDPARAML index, int32* paraml );

dcimg_getparaml() function returns a int32 value into paraml argument with DCIMG_IDPARAML value specified by the index argument.

struct DCIMG_GUID { _ui32 Data1; // unsigned short Data2; // unsigned short Data3; // unsigned char Data4[8]; // };

struct DCIMG_INIT { int32 size; // sizeof(*this) int32 reserved; // reserved const DCIMG_GUID* guid; // GUID option, usually NULL };

struct DCIMG_OPEN { int32 size; // size of this structure int32 codepage; // DCIMG_CODEPAGE_* HDCIMG hdcimg; // LPCTSTR path; // file path };

struct DCIMG_TIMESTAMP { _ui32 sec; // second int32 microsec; // micro second };

struct DCIMG_FRAME { int32 size; // size of this structure. int32 iKind; // 0 reserved int32 option; // DCIMG_FRAME_OPTION int32 iFrame; // frame index void* buf; // pointer for top-left image int32 rowbytes; // byte size for next line DCIMG_PIXELTYPE type; // pixel type in image data int32 width; // horizontal pixel count int32 height; // vertical line count int32 left; // horizontal start pixel int32 top; // vertical start line DCIMG_TIMESTAMP timestamp; // time stamp int32 framestamp; // frame stamp int32 camerastamp; // camera stamp };

struct DCIMG_METADATAHDR { int32 size; // size of whole structure, not only this int32 iKind; // DCIMG_METADATAKIND int32 option; // DCIMG_METADATAOPTION int32 iFrame; // frame index };

struct DCIMG_USERDATATEXT { DCIMG_METADATAHDR hdr; // size member should be size of this structure char* text; // pointer to receive meta data int32 text_len; // byte size of destination buffer int32 codepage; // character encoding value, see DCIMG_CODEPAGE };

struct DCIMG_USERDATABIN { DCIMG_METADATAHDR hdr; // size member should be size of this structure void* bin; // pointer to receive meta data int32 bin_len; // byte size of destination buffer int32 reserved; // 0 reserved };

struct DCIMG_USERDATATEXTBLOCK { DCIMG_METADATAHDR hdr; // size member should be size of this structure void* userdatatext; // pointer for userdatatext block int32 userdatatextsize; // size of one userdatatext int32* userdatatextvalidsize; // return the written data text size of each frame int32 userdatatextmax; // maximum number of userdatatext which can receive int32 userdatatextcount; // number of userdatatext written to buffer int32 userdatatext_kind; // DCIMG_METADATAOPTION__LOCATION int32* userdatatextcodepage; // encode type of each written userdatatext };

struct DCIMG_USERDATABINBLOCK { DCIMG_METADATAHDR hdr; // size member should be size of this structure void* userdatabin; // pointer for userdatabin block int32 userdatabinsize; // size of one userdatabin int32* userdatabinvalidsize; // return the written data bin size of each frame int32 userdatabinmax; // maximum number of userdatabin which can receive int32 userdatabincount; // number of userdatabin written to buffer int32 userdatabin_kind; // DCIMG_METADATAOPTION__LOCATION };

struct DCIMG_TIMESTAMPBLOCK { DCIMG_METADATAHDR hdr; // size member should be size of this structure DCIMG_TIMESTAMP* timestamps; // pointer for TIMESTAMP block int32 timestampmax; // maximum number of timestamp to receive int32 timestampkind; // reserved to return timestamp kind int32 timestampsize; // sizeof(DCIMG_TIMESTAMP) int32 timestampvalidsize; // the written data size of DCIMG_TIMESTAMP int32 timestampcount; // number of timestamp written to timestamps };

struct DCIMG_FRAMESTAMPBLOCK { DCIMG_METADATAHDR hdr; // size member should be size of this structure int32* framestamps; // pointer for framestamp block int32 framestampmax; // maximum number of framestamp to receive int32 framestampcount; // number of framestamp written to buffer int32 reserved; // 0 reserved. };

struct DCIMGDATA_HDR { int32 size; // size of whole structure, not only this int32 iKind; // DCIMGDATA_KIND int32 option; // DCIMGDATA_OPTION int32 reserved; // 0 reserved };

struct DCIMGDATA_REGION { DCIMGDATA_HDR hdr; // iKind = DCIMGDATA_KIND__REGION int32 option; // 0 reserved int32 type; // DCIMGDATA_RETIONTYPE void* data; // top of data int32 datasize; // size of data int32 reserved; // 0 reserved };

struct DCIMGDATA_REGIONRECT { short left; // left side short top; // top side short right; // right side short bottom; // bottom side };

struct DCIMGDATA_SENSORPARAM { DCIMGDATA_HDR hdr; // iKind = DCIMGDATA_KIND__SENSORPARAM int32 option; // 0 reserved int32 binning; // binning int32 sensorhpos; // horizontal offset of sensor int32 sensorhsize; // horizontal size of sensor int32 sensorvpos; // vertical offset of sensor int32 sensorvsize; // vertical size of sensor };