public class MCfile extends MCattributeSet
DICOM media files contain a file meta information and a data set. The file meta information includes a 128 byte preamble and group 0002 attributes identifying the data set. The exact content of the data set depends on its SOP class.
This class can be used to read or write the content of a DICOM file as shown in the example below:
// read the content of the file MCfile p10File = new MCfile(); p10File.readP10File( filePath ); // access attribute values String modality = p10File.getModality(); String accNumber = p10File.getStringValue( MCdicom.ACCESSION_NUMBER, 0 ); // modify attribute values p10File.setValue( MCdicom.PATIENTS_NAME, "Joe" ); // write the content to a file p10File.writeP10File( destFilePath );
Access to both file meta header and data set attribute values is provided through the methods of the base class.
An instance of this class can not be used by multiple threads concurrently.
Constructor and Description |
---|
MCfile()
Initializes a new DICOM media file object.
|
MCfile(com.merge.mcw.CoreAttribSet ats)
Initializes a new DICOM media file object for specified attribute set.
|
MCfile(MCdimseMessage msg)
Initializes a new DICOM file object based on the content of a DIMSE message.
|
MCfile(java.lang.String serviceName)
Initializes a new DICOM media file object for the specified service.
|
Modifier and Type | Method and Description |
---|---|
java.lang.String |
getMediaStorageSOPClassUID()
Gets the value of the Media Storage SOP Class UID attribute in this file's meta information.
|
java.lang.String |
getMediaStorageSOPInstanceUID()
Gets the value of the Media Storage SOP Instance UID attribute in this file's meta information.
|
byte[] |
getPreamble()
Gets the 128 byte preamble from this file's meta information.
|
void |
readP10File(java.nio.channels.ReadableByteChannel source)
Decodes a DICOM media file encoded according to the specifications in Part 10 of the DICOM standard.
|
long |
readP10File(java.nio.channels.ReadableByteChannel source,
int upToTag)
Decodes a DICOM media file encoded according to the specifications in Part 10 of the DICOM standard.
|
long |
readP10File(java.nio.channels.ReadableByteChannel source,
int upToTag,
boolean bypassValue)
Decodes a DICOM media file encoded according to the specifications in Part 10 of the DICOM standard.
|
void |
readP10File(java.lang.String filePath)
Decodes the content a file system file containing a DICOM media file encoded according to the specifications
in Part 10 of the DICOM standard.
|
long |
readP10File(java.lang.String filePath,
int upToTag)
Decodes the content a file system file containing a DICOM media file encoded according to the specifications
in Part 10 of the DICOM standard.
|
long |
readP10File(java.lang.String filePath,
int upToTag,
boolean bypassValue)
Decodes the content a file system file containing a DICOM media file encoded according to the specifications
in Part 10 of the DICOM standard.
|
void |
readP10FileBypassBulk(java.nio.channels.ReadableByteChannel source)
Decodes a DICOM media file encoded according to the specifications in Part 10 of the DICOM standard.
|
void |
readP10FileBypassBulk(java.lang.String filePath)
Decodes the content a file system file containing a DICOM media file encoded according to the specifications
in Part 10 of the DICOM standard.
|
void |
setApplication(MCapplication app)
Associates this file with an application object.
|
void |
setPreamble(byte[] preamble)
Sets the 128 byte preamble of this file.
|
void |
writeP10File(java.lang.String filePath)
Encodes the content of this file object according to the specifications in Part 10 of the DICOM standard.
|
void |
writeP10File(java.nio.channels.WritableByteChannel destination)
Encodes the content of this file object according to the specifications in Part 10 of the DICOM standard.
|
addAttribute, addAttribute, addEncapsulatedFrame, addValue, addValue, clear, clear, contains, contains, copyTo, createSignature, createSignature, deleteSignature, dispose, duplicate, getBigInteger, getBigInteger, getBulkValue, getBulkValue, getCommand, getDoubleValue, getDoubleValue, getEncapsulatedFrame, getFloatValue, getFloatValue, getFrame, getIntValue, getIntValue, getItem, getItem, getKeyword, getKeyword, getLongValue, getLongValue, getModality, getNextValidationError, getOffsetTable, getService, getShortValue, getShortValue, getSOPClassUID, getSOPInstanceUID, getStringValue, getStringValue, getStringValue, getStringValue, getTransferSyntax, getValue, getValue, getValue, getValue, getValueCount, getValueCount, getValueLength, getValueLength, getValueRepresentation, getValueRepresentation, getValues, getValues, iterator, list, list, readAttributeSetsFromJSON, readAttributeSetsFromJSON, readFromJSON, readFromJSON, readFromStream, readFromStream, readFromXML, readFromXML, readFromXMLNative, readFromXMLNative, removeAttribute, removeAttribute, resetTransferSyntax, setDefaultCompression, setServiceCommand, setTransferSyntax, setValue, setValue, setValueRepresentation, setValueRepresentation, size, validate, validateAttribute, verifySignature, writeAttributeSetsToJSON, writeToJSON, writeToStream, writeToStream, writeToXML, writeToXML, writeToXMLNative
public MCfile()
The file object will not be associated with any specific service (SOP class).
The toolkit defaults the transfer syntax of the new file to Explicit Little Endian.
MCexception
- If the toolkit is not initialized.public MCfile(java.lang.String serviceName)
The toolkit defaults the transfer syntax of the new file to Explicit Little Endian.
serviceName
- The name of a DICOM service as specified in the mergecom.srv configuration file.MCexception
- If the toolkit is not initialized.public MCfile(MCdimseMessage msg)
This constructor assigns the data set portion of the message to the new file and disposes the message object.
msg
- The DIMSE message object providing the data set for the file.MCexception
- If the toolkit is not initialized or the message parameter is null
.public MCfile(com.merge.mcw.CoreAttribSet ats)
ats
- The DICOM file object providing the data set for the file.MCexception
- If the attribute set type is not FILE.public byte[] getPreamble()
Note, that modifying the elements of the returned array does not change the file's pramble.
Use the setPreamble(byte[])
method to set or change the preamble.
MCexception
- If the file is disposed.public void setPreamble(byte[] preamble)
preamble
- A 128 byte array containing the preamble data.MCexception
- If the file is disposed or if the parameter is null
or its length
is not 128.public void readP10File(java.lang.String filePath)
This method reads all attributes from the specified file into this file object.
If the application associated with this file object (see setApplication(MCapplication)
) has
a value storage provider registered the toolkit will use it to store values for large attribute values.
filePath
- The source file location.MCexception
- null
.
public long readP10File(java.lang.String filePath, int upToTag)
This method reads attributes with tag numbers up to and including the specified value, and returns the byte offset in the file of the first attribute that was not read. If the source file does not contain the attribute with the specified tag the reading stops before the first attribute with tag number higher than the specified tag.
If the application associated with this file object (see setApplication(MCapplication)
) has
a value storage provider registered the toolkit will use it to store values for large attribute values.
filePath
- The source file location.upToTag
- The tag number of the last attribute to process. The toolkit converts this value to an
unsigned integer so that negative values represent values beyond Integer.MAX_VALUE
. E.g. -327686
(0xFFFAFFFA) represents the tag (FFFA,FFFA).MCexception
- null
.
public long readP10File(java.lang.String filePath, int upToTag, boolean bypassValue)
This method reads attributes with tag numbers up to and including the specified value, and returns the byte offset in the file of the first attribute that was not read. If the source file does not contain the attribute with the specified tag the reading stops before the first attribute with tag number higher than the specified tag.
If the application associated with this file object (see setApplication(MCapplication)
) has
a value storage provider registered the toolkit will use it to store values for large attribute values.
filePath
- The source file location.upToTag
- The tag number of the last attribute to process. The toolkit converts this value to an
unsigned integer so that negative values represent values beyond Integer.MAX_VALUE
. E.g. -327686
(0xFFFAFFFA) represents the tag (FFFA,FFFA).bypassValue
- The flag indicating whether the tag value data should be bypassedMCexception
- null
.
public void readP10File(java.nio.channels.ReadableByteChannel source)
This method decodes all attributes and adds them to this file object.
If the application associated with this file object (see setApplication(MCapplication)
) has
a value storage provider registered the toolkit will use it to store values for large attribute values.
source
- The byte channel providing the encoded DICOM content.MCexception
- null
.
public long readP10File(java.nio.channels.ReadableByteChannel source, int upToTag)
This method reads attributes with tag numbers up to and including the specified value, and returns the number of bytes read from the channel. If the source does not contain the attribute with the specified tag the reading stops before the first attribute with tag number higher than the specified tag.
If the application associated with this file object (see setApplication(MCapplication)
) has
a value storage provider registered the toolkit will use it to store values for large attribute values.
source
- The byte channel providing the encoded DICOM content.upToTag
- The tag number of the last attribute to process. The toolkit converts this value to an
unsigned integer so that negative values represent values beyond Integer.MAX_VALUE
. E.g. -327686
(0xFFFAFFFA) represents the tag (FFFA,FFFA).MCexception
- null
.
public long readP10File(java.nio.channels.ReadableByteChannel source, int upToTag, boolean bypassValue)
This method reads attributes with tag numbers up to and including the specified value, and returns the number of bytes read from the channel. If the source does not contain the attribute with the specified tag the reading stops before the first attribute with tag number higher than the specified tag.
If the application associated with this file object (see setApplication(MCapplication)
) has
a value storage provider registered the toolkit will use it to store values for large attribute values.
source
- The byte channel providing the encoded DICOM content.upToTag
- The tag number of the last attribute to process. The toolkit converts this value to an
unsigned integer so that negative values represent values beyond Integer.MAX_VALUE
. E.g. -327686
(0xFFFAFFFA) represents the tag (FFFA,FFFA).bypassValue
- The flag indicating whether the tag value data should be bypassedMCexception
- null
.
public void readP10FileBypassBulk(java.lang.String filePath)
This method can be used to increase performance for handling attributes of type OB, OW, OV, OL, OD or OF. If the
application associated with this file object (see setApplication(MCapplication)
) has a value
storage provider registered for an attribute of type OB, OW, OV, OL, OD or OF, this method will not store the
attribute's value. Instead, the offset of the attribute's value from the beginning of the file along
with length of the value will be passed to the value storage trough the
MCvalueStorage.receiveMediaDataLength(long, long)
method. When the data is needed by the user
or the toolkit, the value storage can retrieve it from the media. See the description of the
MCvalueStorage
class for more details.
filePath
- The source file location.MCexception
- null
.
public void readP10FileBypassBulk(java.nio.channels.ReadableByteChannel source)
This method can be used to increase performance for handling attributes of type OB, OW, OV, OL, OD or OF. If the
application associated with this file object (see setApplication(MCapplication)
) has a value
storage provider registered for an attribute of type OB, OW, OV, OL, OD or OF, this method will not store the
attribute's value. Instead, the offset of the attribute's value from the beginning of the stream along
with length of the value will be passed to the value storage trough the
MCvalueStorage.receiveMediaDataLength(long, long)
method. When the data is needed by the user
or the toolkit, the value storage can retrieve it from the channel. See the description of the
MCvalueStorage
class for more details.
source
- The byte channel providing the encoded DICOM content.MCexception
- null
.
public void writeP10File(java.lang.String filePath)
This method will automatically fill in the following group 2 attributes, if not already done by the application:
filePath
- The destination file for the encoded stream.MCexception
- null
.
public void writeP10File(java.nio.channels.WritableByteChannel destination)
This method will automatically fill in the following group 2 attributes, if not already done by the application:
destination
- The destination byte channel for the encoded stream.MCexception
- null
.
public void setApplication(MCapplication app)
The associated application supplies attribute value storage for this file through the registered value storage providers.
When decoding, the toolkit checks for each OB, OW, OV, OL, OD or OF type attribute whether there is a storage provider registered with the associated application. For those attributes that have a storage provider registered the toolkit will use a value storage to store the value, it will not store the value internally. This behavior is affected by the CALLBACK_MIN_DATA_SIZE configuration parameter which specifies the minimum size of value for which the value storage feature is used. This option was specifically added so pixel data contained in icons are not managed with value storage. Note that this configuration parameter does no apply to encapsulated pixel data which has undefined length.
When writing, the toolkit checks for each empty OB, OW, OV, OL, OD or OF type attribute whether storage provider registered with the associated application. For those empty attributes that have a storage provider registered the toolkit will use the value storage to read the value.
app
- The application object to associate with this file or null
to de-associate any
application from this file.public java.lang.String getMediaStorageSOPClassUID()
This is a convenience method that provides easy access to the Media Storage SOP Class UID of this
file. This method is equivalent with the following call:
getStringValue(MCdicom.MEDIA_STORAGE_SOP_CLASS_UID, 0, null)
public java.lang.String getMediaStorageSOPInstanceUID()
This is a convenience method that provides easy access to the Media Storage SOP Instance UID of this
file. This method is equivalent with the following call:
getStringValue(MCdicom.MEDIA_STORAGE_SOP_INSTANCE_UID, 0, null)
null
if
the attribute is missing or it has no values.