public final class Header extends Object implements Iterable<Map.Entry<String,Attribute>>
The header contains the set of attributes and channels; it is used for
writing new files and contains all the information from existing ones.
An instance of Header
provides iterator access to the named
attributes. While all aspects of a file are specified as attributes, this
class provides accessors and setters for the attributes which have to be
present in all OpenEXR files.
This class is modeled after ImfHeader
in the original C++ OpenEXR
library.
Constructor and Description |
---|
Header()
Default constructor.
|
Header(Header other)
Copy constructor.
|
Header(int width,
int height)
Creates a header where the display window and the data window are both
set to [0,0] x [width-1, height-1], with an empty channel list.
|
Modifier and Type | Method and Description |
---|---|
Set<String> |
attributeNameSet()
Returns a read-only
Set view of the attribute names contained
in this header. |
Set<Map.Entry<String,Attribute>> |
entrySet()
Returns a read-only
Set view of the name-attribute mappings
contained in this header. |
boolean |
equals(Object obj)
Compares the specified object with this header for equality.
|
void |
erase(String name)
If an attribute with the given name exists, then it is removed from the
map of present attributes.
|
<T> TypedAttribute<T> |
findTypedAttribute(String name,
Class<? extends TypedAttribute<T>> cls)
Returns a reference to the typed attribute with name
n and value
type T , or null if no attribute with name n
and type T exists. |
ChannelList |
getChannels()
Returns a reference to the value of the channels
predefined attribute.
|
Compression |
getCompression()
Returns a reference to the value of the compression
predefined attribute.
|
Box2<Integer> |
getDataWindow()
Returns a reference to the value of the dataWindow
predefined attribute.
|
Box2<Integer> |
getDisplayWindow()
Returns a reference to the value of the displayWindow
predefined attribute.
|
LineOrder |
getLineOrder()
Returns a reference to the value of the lineOrder
predefined attribute.
|
Float |
getPixelAspectRatio()
Returns a reference to the value of the pixelAspectRatio
predefined attribute.
|
Vector2<Float> |
getScreenWindowCenter()
Returns a reference to the value of the screenWindowCenter
predefined attribute.
|
Float |
getScreenWindowWidth()
Returns a reference to the value of the screenWindowWidth
predefined attribute.
|
TileDescription |
getTileDescription()
Returns a reference to the value of the tiles attribute
attribute if and only if
hasTileDescription()
returns true . |
<T> TypedAttribute<T> |
getTypedAttribute(String name,
Class<? extends TypedAttribute<T>> cls)
Returns a reference to the typed attribute with name
n and value
type T . |
int |
hashCode()
Returns the hash code value for this header.
|
boolean |
hasTileDescription()
Returns whether the header contains a
TileDescriptionAttribute
whose name is "tiles". |
void |
insert(String n,
Attribute attr)
Add an attribute to the header.
|
boolean |
isEmpty()
Returns
true if this header contains no name-attribute mappings. |
Iterator<Map.Entry<String,Attribute>> |
iterator()
Returns a read-only iterator over the existing attributes.
|
void |
readFrom(XdrInput input,
int version)
Populates this header by reading from the
XdrInput encapsulating
an input stream, replacing its previous contents. |
static void |
sanityCheck(Header h,
boolean isTiled)
Examines the header, and throws an
IllegalArgumentException if
the header is non-null and it finds something wrong (e.g. |
void |
setCompression(Compression value)
Sets the value of the compression predefined attribute
to
value . |
void |
setDataWindow(Box2<Integer> value)
Sets the value of the dataWindow predefined attribute
to
value . |
void |
setDataWindow(int xMin,
int yMin,
int xMax,
int yMax)
Sets the value of the dataWindow predefined attribute
to the box
[xMin,yMin]x[xMax,yMax] . |
void |
setDisplayWindow(Box2<Integer> value)
Sets the value of the displayWindow predefined attribute
to
value . |
void |
setDisplayWindow(int xMin,
int yMin,
int xMax,
int yMax)
Sets the value of the displayWindow predefined attribute
to the box
[xMin,yMin]x[xMax,yMax] . |
void |
setLineOrder(LineOrder value)
Sets the value of the lineOrder predefined attribute
to
value . |
void |
setPixelAspectRatio(float value)
Sets the value of the pixelAspectRatio predefined attribute
to
value . |
void |
setScreenWindowCenter(float x,
float y)
Sets the value of the screenWindowCenter predefined attribute
to the point
(x,y) . |
void |
setScreenWindowCenter(Vector2<Float> value)
Sets the value of the screenWindowCenter predefined attribute
to
value . |
void |
setScreenWindowWidth(float value)
Sets the value of the screenWindowWidth predefined attribute
to
value . |
int |
size()
Returns the number of name-attribute mappings in this header.
|
int |
version()
Returns the appropriate version number that corresponds to this header.
|
long |
writeTo(XdrOutput output)
Serializes this header by writing into the
XdrOutput
encapsulating an output stream. |
public Header()
Header(int, int)
.public Header(int width, int height) throws IllegalArgumentException
The other predefined attributes are initialized as follows:
Attribute | Value |
---|---|
pixelAspectRatio | 1.0 |
screenWindowCenter | (0.0, 0.0) |
screenWindowWidth | 1.0 |
lineOrder | LineOrder.INCREASING_Y |
compression | Compression.ZIP |
width
- positive width of the file.height
- positive height of the file.IllegalArgumentException
- if either parameter is less than 1.public Header(Header other) throws IllegalArgumentException
other
- the header to duplicate.IllegalArgumentException
- if other
is null
.public Iterator<Map.Entry<String,Attribute>> iterator()
The elements are ordered by attribute name. The returned entries represent snapshots of the attributes at the time they were produced.
public Set<String> attributeNameSet()
Set
view of the attribute names contained
in this header. The set's iterator returns the attribute names in
ascending order.public Set<Map.Entry<String,Attribute>> entrySet()
Set
view of the name-attribute mappings
contained in this header. The set's iterator returns the entries in
ascending name order.public int size()
public boolean isEmpty()
true
if this header contains no name-attribute mappings.
This implementation returns size() == 0
.
true
if this header contains no name-attribute mappingspublic int version()
public void insert(String n, Attribute attr) throws IllegalArgumentException, EXRTypeException
n
exists, a new attribute with name n
and the same type as
attr
, is added, and the value of attr
is copied into
the new attribute.
If an attribute with name n
exists, and its type is the same
as attr
, the value of attr
is copied into this attribute.
If an attribute with name n
exists, and its type is different
from attr
an EXRTypeException
is thrown.
n
- the non-empty name of the attribute.attr
- the non-null attribute to add.IllegalArgumentException
- if n
or attr
are empty
or null
.EXRTypeException
- if an attribute with name n
exists, and
its type is different from attr
.public void erase(String name) throws IllegalArgumentException
name
- the name of the attribute to remove.IllegalArgumentException
- if name
is either null
or empty, or it corresponds to a predefined attribute.public <T> TypedAttribute<T> getTypedAttribute(String name, Class<? extends TypedAttribute<T>> cls) throws IllegalArgumentException, EXRTypeException
n
and value
type T
. If no attribute with name n
exists, an
IllegalArgumentException
is thrown. If an attribute with name
n
exists, but its value type is not T
, an
EXRTypeException
is thrown.
Type limitations: because Java implements generics via type
erasure, Foo<T1>
and Foo<T2>
have the same type; the
parameter types T1
and T2
may only be retrieved for
concrete instances. To avoid very convoluted type checking via reflection
this implementation actually checks that the typed attribute
class itself matches that of the existing attribute. Although this
technically violates the method description, in practice concrete
TypedAttribute
instances are not parameterized and there is
exactly one TypedAttribute
class with value type T
.
name
- non-empty name of the desired attribute.cls
- the class of the concrete TypedAttribute<T>
implementation.n
and value type T
.EXRTypeException
- if an attribute with name n
exists, but
its value type is not T
.IllegalArgumentException
- if no attribute with name
n
exists.NullPointerException
- if either name
or cls
is null
public <T> TypedAttribute<T> findTypedAttribute(String name, Class<? extends TypedAttribute<T>> cls)
n
and value
type T
, or null
if no attribute with name n
and type T
exists.
Type limitations: because Java implements generics via type
erasure, Foo<T1>
and Foo<T2>
have the same type; the
parameter types T1
and T2
may only be retrieved for
concrete instances. To avoid very convoluted type checking via reflection
this implementation actually checks that the typed attribute
class itself matches that of the existing attribute. Although this
technically violates the method description, in practice concrete
TypedAttribute
instances are not parameterized and there is
exactly one TypedAttribute
class with value type T
.
name
- non-empty name of the desired attribute.cls
- the class of the concrete TypedAttribute<T>
implementation.n
and value type T
or null
.NullPointerException
- if either name
or cls
is null
public Box2<Integer> getDisplayWindow()
public void setDisplayWindow(Box2<Integer> value)
value
. This setter method does a deep copy of value
,
it does not copy a reference to it.value
- a non-null Box<Integer>
public void setDisplayWindow(int xMin, int yMin, int xMax, int yMax)
[xMin,yMin]x[xMax,yMax]
.xMin
- minimum x value of the boxyMin
- minimum y value of the boxxMax
- maximum x value of the boxyMax
- maximum y value of the boxpublic Box2<Integer> getDataWindow()
public void setDataWindow(Box2<Integer> value)
value
. This setter method does a deep copy of value
,
it does not copy a reference to it.value
- a non-null Box<Integer>
public void setDataWindow(int xMin, int yMin, int xMax, int yMax)
[xMin,yMin]x[xMax,yMax]
.xMin
- minimum x value of the boxyMin
- minimum y value of the boxxMax
- maximum x value of the boxyMax
- maximum y value of the boxpublic Float getPixelAspectRatio()
public void setPixelAspectRatio(float value)
value
.value
- a float greater than zero.public Vector2<Float> getScreenWindowCenter()
public void setScreenWindowCenter(Vector2<Float> value)
value
. This setter method does a deep copy of value
,
it does not copy a reference to it.value
- a non-null Vector2<Float>
public void setScreenWindowCenter(float x, float y)
(x,y)
.x
- the x component of the pointy
- the y component of the pointpublic Float getScreenWindowWidth()
public void setScreenWindowWidth(float value)
value
.value
- a float greater than zero.public ChannelList getChannels()
public LineOrder getLineOrder()
public void setLineOrder(LineOrder value)
value
.value
- a non-null LineOrder
.public Compression getCompression()
public void setCompression(Compression value)
value
.value
- a non-null Compression
.public TileDescription getTileDescription()
hasTileDescription()
returns true
.
The "tiles" attribute must be present in any tiled image file. When present, it describes various properties of the tiles that make up the file. If the "tiles" attribute is not present this method throws an exception.
public boolean hasTileDescription()
TileDescriptionAttribute
whose name is "tiles".
The "tiles" attribute must be present in any tiled image file.
When present, it describes various properties of the tiles that make up
the file. The implementation simply returns
findTypedAttribute("tiles",TileDescriptionAttribute.class)!=null
.
true
if the header contains a
TileDescriptionAttribute
whose name is "tiles", false
otherwise.public static void sanityCheck(Header h, boolean isTiled) throws IllegalArgumentException
IllegalArgumentException
if
the header is non-null and it finds something wrong (e.g. empty display
window, negative pixel aspect ratio, unknown compression scheme, etc.)h
- the header to verifyisTiled
- whether the header is supposed to have tiles or notIllegalArgumentException
- if there is something wrong
with the filepublic void readFrom(XdrInput input, int version) throws EXRIOException
XdrInput
encapsulating
an input stream, replacing its previous contents.
This method reads a sequence of name-attribute pairs. The names are null-terminated strings; a zero-length attribute name indicates the end of the header. Each attribute is stored as a null-terminated string with the attribute's type name, followed by a 32-bit integer with the length of the attribute's data, followed by that many bytes.
Depending on the version
value the will be specific limitations
on the attribute values and structure of the header.
input
- data source which contains the header dataversion
- OpenEXR version number as stored in the fileEXRIOException
- if there is an error in the file format or
if there is another I/O errorpublic long writeTo(XdrOutput output) throws EXRIOException
XdrOutput
encapsulating an output stream.
This method writes a sequence of name-attribute pairs. The names are null-terminated strings; a zero-length attribute name marks the end of the header. Each attribute is stored as a null-terminated string with the attribute's type name, followed by a 32-bit integer with the length of the attribute's data, followed by that many bytes.
This method does not write neither the version number nor the magic number, it serializes the header data only.
If the header contains a preview image attribute,
then writeTo()
returns the position of that attribute in the
output stream; this information is used to update the preview image
when writing an output file. If the header contains no preview image
attribute, then writeTo()
returns 0.
output
- data sink where the header data will be writtenEXRIOException
- if there is an I/O errorversion()
public int hashCode()
entrySet()
view. This ensures that h1.equals(h2)
implies that h1.hashCode()==h2.hashCode()
for any two headers
h1 and h2, as required by the general contract of
Object.hashCode
.
This implementation relies on the underlying map, which iterates over
entrySet()
, calling hashCode()
on each attribute (entry)
in the set, and adding up the results.
public boolean equals(Object obj)
This implementation first checks if the specified object is this header; if so it returns true. Then, it checks if the specified object is a header whose size is identical to the size of this header; if not, it returns false. If so, it iterates over this header's entrySet collection, and checks that the specified header contains each mapping that this header contains. If the specified header fails to contain such a mapping, false is returned. If the iteration completes, true is returned.