jcupitt
commented
1 year ago Sorry this thing is so huge Markus :( But I think it's done now, modulo the inevitable various bugs and typos, of course.
I would just read dicom.h and the docs, and wave the rest through with a sigh. Checking the whole PR is probably too much work for any sane person. Now it's at 1.0, future changes should be small.
I put a copy of the formatted docs here for your convenience:
http://www.rollthepotato.net/~john/libdicom/
I'll update openslide to this revised API.
fedorov
bgilbert
This PR updates libdicom to 1.0.
The headline changes are:
New parser
The DICOM file parser has been split off to
dicom-parse.c. It's a callback-based parser and knows about the internal structure of PixelData. This generic parser is used bydicom-file.cto load parts of DICOM files into memory, to scan files for features, and to print files to stdout.This parse API is only internal, for now at least.
Revised Filehandle API
The various filehandle API calls can now be called any number of times, and in any order. They are all optional, so it's now possible to simply open a file and immediately call
dcm_filehandle_read_frame().dcm_filehandle_read_file_meta()anddcm_filehandle_read_metadata()have been renamed asdcm_filehandle_get_file_meta()anddcm_filehandle_get_metadata(). These new functions return aconstpointer to libdicom's internal copy of the parsed metadata, and should NOT be destroyed. Usecloneto make a copy if you need the result to live longer.The metadata returned by
dcm_filehandle_get_metadata()is only the metadata which can be read quickly and without using much memory. To read all metadata (so including, for example, the sometimes extremely largePerFrameFunctionalGroupSequence) there's a new API calldcm_filehandle_read_metadata(). This function takes a set of stop tags. If necessary, it can be called many times to read all the file metadata.There's a new API call
dcm_filehandle_read_frame_position()which will read a frame at a certain (column, row) position. It automatically takes account of any ordering inPerFrameFunctionalGroupSequence, if present.DcmBOTis no longer exposed ion the API, since this is now all handled automatically.Automatic handling of byte ordering and implicit versus explicit encoding has been improved.
Revised data model
dcm_sequence_foreach()anddcm_dataset_foreach()have a client pointer, allow early termination, and track sequence index.A new function,
dcm_element_set_value(), can set the value of an element from a generic byte buffer.A new function,
dcm_element_value_to_string(), makes a formatted character string representing the value of an element. It is handy for displaying values to users in an understandable way.Some more of
dicom-dict.cis in the public API, notablyDcmVRClassand associated functions. This was needed by openslide.Revised logging
There's now
dcm_log_set_level()to set the log level (rather than a global variable).If the environment variable
DCM_DEBUGis set, logging defaults toDCM_LOG_DEBUGindcm_init(). For example:New
dcm-dumpThere's a new function,
dcm_filehandle_print(), which prints all metadata in a file, including pixeldata. This is the function used bydcm-dump.The output looks like eg.:
You can see it's displaying the first few bytes of the frame in hex. It knows about OW and OF and OD as well, and encapsulated and native pixeldata.
It has the very nice feature of printing as it parses, so it can display DICOM files of any size very quickly and only using a little memory.
New argument parser
The two tools now use something like getopt to parse command-line arguments and switches, making them more consistent and easier to use.