Merge pull request #50 from jcupitt/update-to-v0.2

Update to v0.2

Author: jcupitt

TODO

@@ -1,32 +1,24 @@
 # TODO
 
+- need to be able to set a stop-at function on filehandles
+
+
 # bot support
 
 - need more tests and test images
 
 - extended offset table support seems to be broken? see FIXME comment
 
-- bot frame offsets should be int64_t to match dcm_seekset(), 
-  pixel_data_offset, etc.
-
-
-# less copy-paste
+	probably will never be used
 
-- replace copy-paste code over types with a table
-	dcm_element_clone()
+- a fast scanner to find the BOT table
 
-- use a table for dcm_element_create_* as well
-
-
-# more enums
-
-- element->vr should be an enum (not "UL" etc.)
-	- swap all the strcmps for ==
-
-- benchmark against the original 
 
 # data types
 
+- bot frame offsets should be int64_t to match dcm_seekset(), 
+  pixel_data_offset, etc.
+
 - should create_element() take a size_t for length?
 
 - remove dcm_dataset_copy_tags() etc should not use uint32_t? what about
@@ -38,16 +30,6 @@
 
 	no, it's unsigned int
 
-- dcm_dataset_print() should not use uint8_t
-
-
-# revise pointer ownership rules
-
-- right now, _create funcs free passed in objects on error which feels very 
-  error-prone
-
-  instead, the caller should free on error ... how easy would this be to change?
-
 
 # asserts
 
@@ -76,3 +58,8 @@
 - debug failing test with eg.
 
 	CK_FORK=no CK_RUN_CASE=frame gdb ./check_dicom
+
+- leak check
+
+	CK_FORK=no valgrind --leak-check=full ./check_dicom
+

doc/source/usage.rst

@@ -1,23 +1,22 @@
 Usage
 -----
 
-Memory management
-+++++++++++++++++
-
-Each data structure (Data Element, Data Set, Sequence, Frame Item, etc.) takes
-over ownership of allocated memory for passed arguments upon object creation
-(``*_create()`` functions) and deallocates the memory upon object destruction
-(``*_destroy()`` functions).  Note that if the creation of a data structure
-fails, the memory of the passed arguments will also be freed.
-
-
 API overview
 ++++++++++++
 
 A `Data Element
 <http://dicom.nema.org/medical/dicom/current/output/chtml/part05/chapter_3.html#glossentry_DataElement>`_
 (:c:type:`DcmElement`) is an immutable data container for
-storing values.  Every Data Element has a `Value Representation (VR)
+storing values.  
+
+Every data element has a tag indicating its purpose. Tags are 32-bit
+unsigned ints with the top 16 bits indicating the group and the bottom 16 the
+element. They are usually written in hexadecimal, perhaps 0x00400554, meaning
+element 0x554 of group 0x40, or as keywords, in this case `SpecimenUID`. You
+can get the tag from its corresponding keyword with :c:func:`dcm_dict_tag_from_keyword()`,
+or find the keyword from a tag with :c:func:`dcm_dict_keyword_from_tag()`.
+
+Every Data Element has a `Value Representation (VR)
 <http://dicom.nema.org/medical/dicom/current/output/chtml/part05/sect_6.2.html>`_,
 which specifies the data type and format of the contained value.  VRs can
 be conceptually grouped into numbers (integers or floating-point values),
@@ -26,17 +25,27 @@ or scientific notation), character strings (text of restriction length and
 character repertoire), or byte strings (unicode).  Each VR is represented
 using a standard C type (e.g,. VR ``"US"`` has type ``uint16_t`` and VR
 ``"UI"`` has type ``char *``) and additional value constraints may be checked
-at runtime (e.g., the maximal capacity of a character string).  Depending
-on the VR, an individual Data Element may have a `Value Multiplicity (VM)
+at runtime (e.g., the maximal capacity of a character string).  
+
+The VR must be appropriate for the tag. Use :c:func:`dcm_vr_from_tag()` to
+find the set of allowed VRs for a tag. Use :c:func:`dcm_is_valid_vr_for_tag()`
+to check if a VR is allowed for a tag.
+
+Depending on the VR, an individual Data
+Element may have a `Value Multiplicity (VM)
 <http://dicom.nema.org/medical/dicom/current/output/chtml/part05/sect_6.4.html>`_
-greater than one, i.e., contain more than one value.  Under the
-hood, a Data Element thus generally contains an array of values.
-A Data Element can be created via the VR-specific constructor
-function (e.g., :c:func:`dcm_element_create_UI()`) and destroyed
-via :c:func:`dcm_element_destroy()`.  Upon creation, the Data Element
-takes over ownership of the memory allocated for the contained values.
-An individual value can be retrieved via the VR-specific getter function
-(e.g., :c:func:`dcm_element_get_value_UI()`).  Note that in case of character
+greater than one, i.e., contain more than one value.  Under the hood,
+a Data Element may thus contain an array of values.
+
+A Data Element can be created with :c:func:`dcm_element_create()`, it can have
+a value assigned to it with eg.
+:c:func:`dcm_element_set_value_integer()`, and it can be destroyed with 
+:c:func:`dcm_element_destroy()`. See `Memory management <Memory Management_>`_ below for details on
+pointer ownership.
+
+An individual value can be retrieved via the getter functions like
+(e.g., :c:func:`dcm_element_get_value_integer()`).  Note that in case of 
+character
 string or binary values, the getter function returns the pointer to the
 stored character array  (``const char *``) and that pointer is only valid
 for the lifetime of the Data Element.  When a Data Element is destroyed,
@@ -51,17 +60,20 @@ created via :c:func:`dcm_dataset_create()` and destroyed via
 :c:func:`dcm_dataset_destroy()`.  Data Elements can be added to a
 Data Set via :c:func:`dcm_dataset_insert()`, removed from a Data Set
 via :c:func:`dcm_dataset_remove()`, and retrieved from a Data Set via
-:c:func:`dcm_dataset_get()` or :c:func:`dcm_dataset_get_clone()`.  When a
-Data Element is added to a Data Set, the Data Set takes over ownership
+:c:func:`dcm_dataset_get()` or :c:func:`dcm_dataset_get_clone()`.
+
+When a Data Element is added to a Data Set, the Data Set takes over ownership
 of the memory allocated for contained Data Elements.  When a Data Element
 is retrieved from a Data Set, it may either be borrowed with ownership of
 the memory allocated for the Data Element remaining with the Data Set in
 case of :c:func:`dcm_dataset_get()` or copied with the caller taking on
 ownership of the memory newly allocated for the Data Element in case of
-:c:func:`dcm_dataset_get_clone()`.  Furthermore, an individual Data Element
-can only be part of only one Data Set.  When a Data Element is removed from a
-Data Set, the memory allocated for the Data Element is freed.  When a Data Set
-is destroyed, all contained Data Elements are also automatically destroyed.
+:c:func:`dcm_dataset_get_clone()`.
+
+An individual Data Element can only be part of only one Data Set.  When a
+Data Element is removed from a Data Set, the memory allocated for the Data
+Element is freed.  When a Data Set is destroyed, all contained Data Elements
+are also automatically destroyed.
 
 A `Sequence
 <http://dicom.nema.org/medical/dicom/current/output/chtml/part05/chapter_3.html#glossentry_SequenceOfItems>`_
@@ -72,22 +84,27 @@ via :c:func:`dcm_sequence_create()` and destroyed via
 :c:func:`dcm_sequence_destroy()`.  Data Sets can be added to a Sequence
 via :c:func:`dcm_sequence_append()`, removed from a Sequence via
 :c:func:`dcm_sequence_remove()`, and retrieved from a Sequence via
-:c:func:`dcm_sequence_get()`.  When a Data Set is added to a sequence,
-the sequence takes over ownership of the memory allocated for the Data Set
-(and consequently of each contained Data Element).  When a Data Set is
-retrieved from a sequence, it is only borrowed and ownership of the memory
-allocated for the Data Set remains with the sequence.  Retrieved Data Sets
-are immutable (locked).  When a Data Set is removed from a sequence, the
-Data Set is destroyed (i.e., the allocated memory is freed).  When a Sequence
-is destroyed, all contained Data Sets are also automatically destroyed.
+:c:func:`dcm_sequence_get()`.  
+
+When a Data Set is added to a sequence, the sequence takes over ownership of
+the memory allocated for the Data Set (and consequently of each contained
+Data Element).  When a Data Set is retrieved from a sequence, it is only
+borrowed and ownership of the memory allocated for the Data Set remains
+with the sequence.  Retrieved Data Sets are immutable (locked).  When a
+Data Set is removed from a sequence, the Data Set is destroyed (i.e., the
+allocated memory is freed).  When a Sequence is destroyed, all contained
+Data Sets are also automatically destroyed.
 
 A Filehandle (:c:type:`DcmFilehandle`) enables access of a `DICOM file
 <http://dicom.nema.org/medical/dicom/current/output/chtml/part10/chapter_3.html#glossentry_DICOMFile>`_,
 which contains an encoded Data Set representing a SOP Instance.
 A Filehandle can be created via :c:func:`dcm_filehandle_create_from_file()`
-and destroyed via :c:func:`dcm_filehandle_destroy()`, which open a
-Part10 file stored on disk and closes it, respectively.  The content of
-a Part10 file can be read using various functions.  The `File Meta Information
+or :c:func:`dcm_filehandle_create_from_memory()` , and destroyed via
+:c:func:`dcm_filehandle_destroy()`.  You can make your own load functions
+to load from other IO sources, see :c:func:`dcm_filehandle_create()`.
+
+The content of a Part10 file can be read
+using various functions.  The `File Meta Information
 <http://dicom.nema.org/medical/dicom/current/output/chtml/part10/chapter_3.html#glossentry_FileMetaInformation>`_
 can be read via :c:func:`dcm_filehandle_read_file_meta()`.  The metadata
 of the Data Set (i.e., all Data Elements with the exception of the Pixel
@@ -159,13 +176,44 @@ For example:
         return 0;
     }
 
-Load from memory
-++++++++++++++++
+Memory management
++++++++++++++++++
 
-As well as :c:func:`dcm_filehandle_create_from_file()`, there's
-:c:func:`dcm_filehandle_create_from_memory()` to make a DcmFilehandle from
-a memory area containing a DICOM image. You can make your own load functions
-to load from other IO sources, see :c:func:`dcm_filehandle_create()`.
+libdicom objects (Data Element, Data Set, Sequence, Frame Item, etc.) can
+contain references to other libdicom objects. For example, you can set a
+sequence as the value of an element like this:
+
+.. code-block:: c
+
+    if (!dcm_element_set_value_sequence(error, element, sequence)) {
+        handle error;
+    }
+
+If this function succeeeds, ownership of the sequence object passes to the
+element, i.e., when the element is destroyed, the sequence will also be
+destroyed.
+
+If this function fails, ownership does not transfer.
+
+libdicom objects can also contain references to data structures allocated by
+other programs, for example, arrays of numeric values. 
+
+.. code-block:: c
+
+    int *values = pointer to array of integers;
+    uint32_t vm = number of ints in array;
+    if( !dcm_element_set_value_numeric_multi(error, 
+                                             element, 
+                                             values, 
+                                             vm, 
+                                             true)) {
+      handle error;
+    }
+
+The final parameter, `steal` sets whether ownership of the pointer to the 
+array should be "stolen" by libdicom. If it is true, then libdicom will use 
+:c:func:`free()` to free the array when the element is freed. If it is false,
+libdiom will take a copy of the array.
 
 Getting started
 +++++++++++++++
@@ -196,6 +244,7 @@ printing it to standard output:
             dcm_filehandle_destroy(filehandle);
             return 1;
         }
+
         dcm_dataset_print(metadata, 0);
 
         dcm_filehandle_destroy(filehandle);