vicar Module
VICAR File Support Module, PDS Ring-Moon Systems Node, SETI Institute
Introduction
vicar is a Python module that supports reading and writing of JPL’s VICAR file format. It supports the definition of the VICAR file format as found here:
Getting Started
The vicar modules provies these classes:
VicarLabel: Class for reading, writing, and parsing of VICAR labels.
VicarImage: Class for handling VICAR image (and other) data files.
VicarError: Extension of class ValueError to contain exceptions.
To read a VICAR image file:
import vicar
vic = vicar.VicarImage("path/to/file")
The returned VicarImage object “vic” has these attributes:
vic.array: The 3-D data array converted to native format.
vic.array2d: Same as above, but with leading dimension (typically, bands) stripped.
vic.prefix: The array prefix bytes as a 3-D array of unsigned bytes.
vic.prefix2d: Same as above, but with the leading dimension stripped.
vic.binheader: The binary header as a bytes object; use vic.binheader_array() to extract information.
vic.label: The internal VicarLabel object that manages the VICAR label information, if direct access is needed.
VICAR parameter values can be extracted from the label using dictionary-like syntax:
len(vic) # the number of parameters in the VICAR label.
vic['LBLSIZE'] # the value of the LBLSIZE parameter (an integer).
vic[0] # the value of the first parameter.
vic[-1] # the value of the last parameter.
vic['LBLSIZE',-1] # the value of the last occurrence of the LBLSIZE parameter.
vic.get(('LBLSIZE',2), 99)
# the value of the third occurrence of the LBLSIZE
# parameter, or 99 if there are fewer than 3 occurrences.
vic.arg('LBLSIZE') # the numeric index of "LBLSIZE" among the VICAR parameters.
You can also use dictionary-like syntax to modify and insert header values:
vic['SOLDIST'] = 1.e9 # set SOLDICT to this value.
del vic['SOLDIST',0] # Remove the first occurrence of SOLDIST from the label.
vic['LBLSIZE+'] = 2000 # insert a new LBLSIZE parameter instead of modifying an
# existing one.
Note that certain required VICAR parameters contain structural information about the file; these cannot generally be modified directly.
Numerous methods are available to iterate over the VICAR label parameters:
for (name,value) in vic.items(): ...
for key in vic.keys(): ...
for name in vic.names(): ...
for value in vic.values(): ...
Iterators can take a regular expression as input to restrict the items returned:
for value in vic.values(r'LAB\d\d'): ...
Use str(vic) to get the VICAR label content represented as a string.
Here are the steps to create and write a VICAR image file:
vic = VicarImage()
vic.array = array
vic.prefix = prefix
vic.binheader = binheader
vic['NOTES'] = ['add as many more VICAR parameters', 'as you wish']
vic.write_file("path/to/file")
- exception vicar.VicarError[source]
Bases:
ValueErrorValueError subclass for violations of the VICAR format standard.
- class vicar.VicarImage(source=None, array=None, *, prefix=None, binheader=None, strict=True)[source]
Bases:
objectConstructor for a VicarImage.
This class defines the contents of a VICAR data file. It supports methods for reading and writing files and for accessing header information.
Properties:
array: The 3-D data array converted to native format.
array3d: Same as above.
array2d: Same as above, but with leading dimension (typically, bands) stripped.
prefix: The array prefix bytes as a 3-D array of unsigned bytes.
prefix3d: Same as above.
prefix2d: Same as above, but with the leading dimension stripped.
binheader: The binary header as a bytes object; use vic.binheader_array() to extract information.
label: The internal object that manages the VICAR label information, available if direct access to it is needed.
Core Methods:
arg: The index of a parameter name within this label.
args: Iterator over the numeric indices of the parameters in a label.
binheader_array: Interpret the content of a binary header.
copy: A copy of this VicarImage.
deepcopy: An independent (deep) copy of this VicarImage.
from_array: Construct a VicarImage object for a NumPy array.
from_file: Construct a VicarImage object from the content of a VICAR data file.
get: Retrieve a label parameter value or return a default.
items: Iterator over the (name, value) tuples in the label.
keys: Iterator over the parameter names in the label as unique keys.
names: Iterator over the parameter names in the label.
values: Iterator over the parameter values in the label.
write_file: Write this object as a VICAR data file.
Python Syntax Support Methods:
__contains__: Enables “name in image” syntax for checking a name in the label.
__delitem__: Enables “del image[name]” syntax to remove a label parameter name.
__eq__: Enables “a == b’, the test of whether two image objects are equal.
__getitem__: Enables “image[name]” dictionary-like syntax to get the value of a label parameter.
__iter__: Enables “for key in image:” syntax to iterate over the label parameter keys.
__len__: Enables “len(image)”, the number of parameters in the image’s label.
__repr__: Enables “repr(image)”, similar to the “str(label)”, but with the class name included.
__setitem__: Enables “image[name] = value” dictionary-like syntax to set the value of a label parameter.
__str__: Enables “str(image)”, returning a string representing the content of a label.
Notes About Dictionary Keys:
When using dictionary-like syntax to reference a parameter in a VICAR label, a rich set of options are available. For example, if image is a VicarImage object, then:
image[n] where n is an integer refers to the “nth” parameter in the label. n can be positive or negative.
image[name] where name is a string refers to the first occurrence in the label of a parameter with this name.
image[name,n] refers to the “nth” occurrence in the label of a parameter with this name. n can be positive or negative.
image[name, after] where both items are strings refers to the first occurrence of parameter name after the first occurrence of parameter after and before the second occurrence of after.
image[name, after, value] refers to the first occurrence of parameter name after the first location where after equals value and before the next occurrence of after.
The last two options make it easy to reference a VICAR label parameter that is repeated. For example, “image[‘DAT_TIM’, ‘TASK’, ‘COPY’]” uniquely identifies the occurrence of DAT_TIM applicable to TASK=’COPY’ when there might be other TASK sections of the image label containing other values of DAT_TIM.
Append a “+” to name to expand upon the function’s behavior. With “get” operations, a list is returned identifying all of the occurrences of the selected name rather than just the first or “nth”. With “set” operations, a new occurrence of name is inserted into the label even if the a parameter of the given name is already present.
- __contains__(key)[source]
True if the given key can is found in the label of this VicarImage.
- Parameters:
key (int, str, or tuple) –
The key identifying the label parameter to check.
int = n: The “nth” parameter in the label. n can be positive or negative.
str = name: The first occurrence in the label of a parameter with this name.
(str, int) = (name, n): The “nth” occurrence in the label of a parameter with this name. n can be positive or negative.
(str, str) = (name, after): The first occurrence of parameter name after the first occurrence of parameter after and before the second occurrence of after.
(str, str, any) = (name, after, value): The first occurrence of parameter name after the first location where after equals value and before the next occurrence of after.
The last two options make it easy to reference a VICAR label parameter that is repeated. For example, if image is a VicarImage, then “image[‘DAT_TIM’, ‘TASK’, ‘COPY’]” uniquely identifies the occurrence of DAT_TIM applicable to TASK=’COPY’ when there might be other TASK sections of the label containing other values of DAT_TIM.
- Returns:
True if the key is found within the label.
- Return type:
bool
- __delitem__(key)[source]
Delete the value of the VICAR parameter identified by the given key.
- Parameters:
key (int, str, or tuple) –
The indexing key, interpreted as follows:
int = n: The “nth” parameter in the label. n can be positive or negative.
str = name: The first occurrence in the label of a parameter with this name.
(str, int) = (name, n): The “nth” occurrence in the label of a parameter with this name. n can be positive or negative.
(str, str) = (name, after): The first occurrence of parameter name after the first occurrence of parameter after and before the second occurrence of after.
(str, str, any) = (name, after, value): The first occurrence of parameter name after the first location where after equals value and before the next occurrence of after.
The last two options make it easy to reference a VICAR label parameter that is repeated. For example, if image is a VicarImage, then “image[‘DAT_TIM’, ‘TASK’, ‘COPY’]” uniquely identifies the occurrence of DAT_TIM applicable to TASK=’COPY’ when there might be other TASK sections of the label containing other values of DAT_TIM.
Append a “+” to name to delete all of the label parameters whose names match the constraints, starting with the first or “nth”.
- Raises:
IndexError – If any numeric component of the key is out of range.
KeyError – If the parameter name is not present in the label (or the section of the label defined by after_name and after_value), or if the key format is unrecognized.
TypeError – If the key is not a recognized type or contains a component that is not of a recognized type.
ValueError – If no identified parameter equals value or if no occurrence of after_name equals after_value.
- __eq__(other)[source]
True if this VicarImage is equal to the given object.
VicarImages are equal if the label content, data array, prefix array, binary header are all equal. Label formatting hints need not be the same.
- Parameters:
other (VicarImage) – Second VicarImage to compare with this.
- Returns:
True if the objects are equal.
- Return type:
bool
- __getitem__(key)[source]
Retrieve the value or values of the VICAR parameter defined by key, using various indexing options.
- Parameters:
key (int, name, or tuple) –
The indexing key, interpreted as follows:
int = n: The “nth” parameter in the label. n can be positive or negative.
str = name: The first occurrence in the label of a parameter with this name.
(str, int) = (name, n): The “nth” occurrence in the label of a parameter with this name. n can be positive or negative.
(str, str) = (name, after): The first occurrence of parameter name after the first occurrence of parameter after and before the second occurrence of after.
(str, str, any) = (name, after, value): The first occurrence of parameter name after the first location where after equals value and before the next occurrence of after.
The last two options make it easy to reference a VICAR label parameter that is repeated. For example, if image is a VicarImage, then “image[‘DAT_TIM’, ‘TASK’, ‘COPY’]” uniquely identifies the occurrence of DAT_TIM applicable to TASK=’COPY’ when there might be other TASK sections of the label containing other values of DAT_TIM.
Append a “+” to the name to return a list of all values where the constraints are satisfied, starting with the first or “nth”.
- Returns:
The value of the indexed parameter if there is no name ending in “+”; otherwise, a list of all the parameter values starting with the “nth”.
- Return type:
int, float, string, or list
- Raises:
IndexError – If any numeric component of the key is out of range.
KeyError – If the parameter name is not present in the label (or the section of the label defined by after_name and after_value), or if the key format is unrecognized.
TypeError – If the key is not a recognized type or contains a component that is not of a recognized type.
ValueError – If no identified parameter equals value or if no occurrence of after_name equals after_value.
- __init__(source=None, array=None, *, prefix=None, binheader=None, strict=True)[source]
Constructor for a VicarImage object.
- Parameters:
source (FCPath, Path, str, or VicarLabel, optional) – Source for the VicarImage based on a file path or VicarLabel; if not specified (equvalent to source=None), a minimal label is created.
array (array-like, optional) – Optional data array for this object. If the source is a file path, this array will override that in the file.
prefix (array-like, optional) – Optional prefix bytes for this object. If the source is a file path, this value will override that in the file. To remove the prefix array found in the file, use prefix=[].
binheader (array-like or bytes, optional) – Optional binary header for this data file. If the source is a file path, this value will override that in the file. To remove the binheader found in the file, use binheader=b’’.
strict (bool, optional) – True (the default) to require strict conformance to the VICAR standard; False for a looser version of the standard. If source is a VicarLabel, this input is ignored; the value already assigned to the source is used instead.
- __iter__()[source]
Iterator over the unique names or (name, occurrence) pairs in the label of this VicarImage.
- Returns:
The parameter keys within this label, in order. The key is the parameter name if it is unique or (name, occurrence number) otherwise.
- Return type:
iterator
- __len__()[source]
The number of keywords in the label of this VicarImage.
- Returns:
Number of parameters in the VICAR label
- Return type:
int
- __setitem__(key, value)[source]
Set the value of the VICAR parameter defined by the given key; define a new parameter name and value if necessary.
- Parameters:
key (int, str, or tuple) –
The indexing key, interpreted as follows:
int = n: The “nth” parameter in the label. n can be positive or negative.
str = name: The first occurrence in the label of a parameter with this name.
(str, int) = (name, n): The “nth” occurrence in the label of a parameter with this name. n can be positive or negative.
(str, str) = (name, after): The first occurrence of parameter name after the first occurrence of parameter after and before the second occurrence of after.
(str, str, any) = (name, after, value): The first occurrence of parameter name after the first location where after equals value and before the next occurrence of after.
The last two options make it easy to reference a VICAR label parameter that is repeated. For example, if image is a VicarImage, then “image[‘DAT_TIM’, ‘TASK’, ‘COPY’]” uniquely identifies the occurrence of DAT_TIM applicable to TASK=’COPY’ when there might be other TASK sections of the label containing other values of DAT_TIM.
Append a “+” to the name to force a new occurrence of the key to be inserted, even if the key already exists.
value (int, float, string, list, or tuple) –
Value to assign to the indexed entry in the label.
Optional formatting can be included if a user wants additional control over how this value will be formatted in the label string will be formatted, by replacing the value with a tuple (value, hints…). See
Notesfor details about formatting hints.
- Raises:
IndexError – If any numeric component of the key is out of range.
KeyError – If the parameter name is not present in the label (or the section of the label defined by after_name and after_value), or if the key format is unrecognized.
TypeError – If the key is not a recognized type or contains a component that is not of a recognized type.
ValueError – If no identified parameter equals value or if no occurrence of after_name equals after_value.
Notes
Formatting hints can be included wherever a VICAR parameter value is specified; simply replace the value by a tuple (value, hints…).
Hints can be specified using up to four items:
([format][[[, name_blanks], val_blanks], sep_blanks])
where:
format is a format string, e.g., “%+7d” or “%7.3f”.
name_blanks is the number of blank characters after the name and before the equal sign; zero by default.
val_blanks is the number of blank characters after the equal sign and before the value; zero by default.
sep_blanks is the number of blanks after the value and before the next label parameter or the label’s end; two by default.
Note the use of square brackets in the tuple expression above. If the first hint value is a string, it is interpreted as format; otherwise, the format is unspecified. After the optional format, values are interpreted as numbers of blanks. If only one int is provided, it defines sep_blanks, with val_blanks and name_blanks set to zero. If two trailing ints are provided, they define val_blanks and sep_blanks, with name_blanks set to zero.
For example, if the name is “TEXP” and the value is 1.5, this is how hint values are interpreted:
<no hints> = ("", 0, 0, 0) -> "TEXP=1.5 " "%.3f" = ("%.3f", 0, 0, 0) -> "TEXP=1.500 " ("%.3f", 4) = ("%.3f", 0, 0, 4) -> "TEXP=1.500 " ("%.3f", 1, 4) = ("%.3f", 0, 1, 4) -> "TEXP= 1.500 " ("%.3f", 2, 1, 4) = ("%.3f", 2, 1, 4) -> "TEXP = 1.500 " 4 = ("", 0, 0, 4) -> "TEXP=1.5 " (1, 4) = ("", 0, 1, 4) -> "TEXP= 1.5 " (2, 1, 4) = ("", 2, 1, 4) -> "TEXP = 1.5 "
When the parameter value is a list, it is also possible to embed formatting information on an item by item basis. Replace any item value by a tuple:
(item [, format][[, blanks_before], blanks_after])
where:
format is a format string, e.g., “%+07d”, “%12.3e” or “%.4f”.
blanks_before is the number of blanks before the value, after the left parenthesis or comma; zero is the default.
blanks_after is the number of blanks after the value and before the next comma or the right parenthesis; zero is the default.
Here are some examples of a list with embedded formatting for a parameter named “XY” with a value [7,6]:
[(7, "%+02d"), 6] = [(7, "%+02d", 0, 0), 6] -> "XY=[+07, 6] " [(7, 2), 6] = [(7, "", 0, 2), 6] -> "XY=[7 , 6] " [(7, 1, 2), 6]) = [(7, "", 1, 2), 6] -> "XY=[ 7 , 6] " [(7, "%02d", 2), 6]) = [(7, "%02d", 0, 2), 6] -> "XY=[07 , 6] " [(7, "%02d", 1, 2), 6]) = [(7, "%02d", 1, 2), 6] -> "XY=[ 07 , 6] "
- arg(key)[source]
The index or indices of the keyed item in the label of this VicarImage.
- Parameters:
key (int, name, or tuple) –
The indexing key, interpreted as follows:
int = n: The “nth” parameter in the label. n can be positive or negative.
str = name: The first occurrence in the label of a parameter with this name.
(str, int) = (name, n): The “nth” occurrence in the label of a parameter with this name. n can be positive or negative.
(str, str) = (name, after): The first occurrence of parameter name after the first occurrence of parameter after and before the second occurrence of after.
(str, str, any) = (name, after, value): The first occurrence of parameter name after the first location where after equals value and before the next occurrence of after.
The last two options make it easy to reference a VICAR label parameter that is repeated. For example, if image is a VicarImage, then “image[‘DAT_TIM’, ‘TASK’, ‘COPY’]” uniquely identifies the occurrence of DAT_TIM applicable to TASK=’COPY’ when there might be other TASK sections of the label containing other values of DAT_TIM.
Append a “+” to the name to return a list of all indices where the constraints are satisfied, starting with the first or “nth”.
value (int, float, or string, optional) – If provided, the identified parameter must equal this value. For an integer key, if the indexed parameter does not have this value, ValueError is raised. For any key involving a name, values of the named parameter that do not match value are skipped over until the one(s) with the correct value are found.
- Returns:
If “+” is appended to name, the list of all positive indices that identify matching parameters, starting with the “nth”. Otherwise, the single positive index into the label identifying the parameter.
- Return type:
int or list[int]
- Raises:
IndexError – If any numeric component of the key is out of range.
KeyError – If the parameter name is not present in the label (or the section of the label defined by after_name and after_value), or if the key format is unrecognized.
TypeError – If the key is not a recognized type or contains a component that is not of a recognized type.
ValueError – If no identified parameter equals value or if no occurrence of after_name equals after_value.
- args(pattern=None)[source]
Iterator over the numerical indices of the keywords in the label of this VicarImage.
- Parameters:
pattern (str or re.Pattern, optional) – Regular expression that can be used to filter the label parameter names.
- Returns:
The indices of the matching parameter names within this label, in order.
- Return type:
iterator
- property array
The data array.
- Returns:
The data array if it is present; otherwise, None.
- Return type:
np.ndarray or None
- property array2d
The data array as 2-D.
- Returns:
The data array as 2-dimensional if it is present; otherwise, None.
- Return type:
np.ndarray or None
- Raises:
VicarError – If the array has more than two dimensions.
- property array3d
The data array as 3-D.
- Returns:
The data array as 3-dimensional if it is present; otherwise, None.
- Return type:
np.ndarray or None
- as_dict()[source]
The VicarLabel object.
DEPRECATED, provided primarily for backward compatibility. Use the label property instead, because it behaves as a dictionary.
- Returns:
The VicarLabel object associated with this VicarImage.
- Return type:
- property binheader
The binary header as an array or bytes object.
- Returns:
The binary header if present; otherwise, None.
- Return type:
np.ndarray, bytes, or None
- binheader_array(kind='', size=None)[source]
The numbers embedded in a binary header.
This method is capable of reading “ISIS” table files when those tables consist entirely of a single data format. It uses the FMT_DEFAULT parameter to determine dtype, and uses the NR and NC values, if present, to determine the number of rows and columns in the table.
- Parameters:
kind (str, optional) – Optional single-letter code for the data type: “u” for unsigned int; “i” for signed int; “f” for float. If not specified, the kind is inferred from the value of the FMT_DEFAULT parameter.
size (int, optional) – Number of bytes per value. If not provided, it is inferred from the FMT_DEFAULT parameter if present. Otherwise, the default is 1 for kind = “u”; 2 for kind = “i”; 4 for kind = “f”.
- Returns:
The binary header as an array; None if there is no binary header.
- Return type:
np.ndarray or None
- copy()[source]
A copy of this VicarImage.
The copied label is independent of the original, but the data and prefix array are shared.
- Returns:
The copy.
- Return type:
- property data_2d
The data array as 2-D; DEPRECATED name.
- Returns:
The data array as 2-dimensional if it is present; otherwise, None.
- Return type:
np.ndarray or None
- Raises:
VicarError – If the array has more than two dimensions.
- property data_3d
The data array as 3-D; DEPRECATED name.
- Returns:
The data array as 3-dimensional if it is present; otherwise, None.
- Return type:
np.ndarray or None
- deepcopy()[source]
An independent (deep) copy of this VicarImage.
- Returns:
The deep copy.
- Return type:
- property filepath
The path to the associated file.
- Returns:
The path to the associated file, if any.
- Return type:
FCPath or None
- static from_array(array, strict=True)[source]
Construct a VicarImage object for an array.
- Parameters:
array (array-like) – The data array to use in this VicarImage object.
strict (bool, optional) – True (the default) to require strict conformance to the VICAR standard; False for a looser version of the standard.
- Returns:
A new VicarImage object containing this data array.
- Return type:
- static from_file(filepath, extraneous='ignore', strict=True)[source]
VicarImage object from an existing VICAR image file.
- Parameters:
filepath (FCPath, Path, or str) – Path to an existing VICAR data file.
extraneous (str, optional) –
How to handle the presence of extraneous bytes at the end of the file, one of:
”error” to raise VicarError;
”warn” to raise a UserWarning;
”print” to print a message;
”ignore” to ignore;
”include” to include the extraneous bytes as part of the return.
strict (bool, optional) – True (the default) to require strict conformance to the VICAR standard; False for a looser version of the standard.
- Returns:
A VicarImage or a tuple containing:
VicarImage: A new object containing the content of the specified file.
bytes or None: Any extraneous bytes from the end of the file, included if extraneous equals “include”.
- Return type:
VicarImage or (VicarImage, bytes or None)
- get(key, default)[source]
Retrieve the value of the VICAR parameter defined by the given key, using various indexing options.
If the key is not found, return a specified default value.
- Parameters:
key (int, str, or tuple) –
The indexing key, interpreted as follows:
int = n: The “nth” parameter in the label. n can be positive or negative.
str = name: The first occurrence in the label of a parameter with this name.
(str, int) = (name, n): The “nth” occurrence in the label of a parameter with this name. n can be positive or negative.
(str, str) = (name, after): The first occurrence of parameter name after the first occurrence of parameter after and before the second occurrence of after.
(str, str, any) = (name, after, value): The first occurrence of parameter name after the first location where after equals value and before the next occurrence of after.
The last two options make it easy to reference a VICAR label parameter that is repeated. For example, if image is a VicarImage, then “image[‘DAT_TIM’, ‘TASK’, ‘COPY’]” uniquely identifies the occurrence of DAT_TIM applicable to TASK=’COPY’ when there might be other TASK sections of the label containing other values of DAT_TIM.
Append a “+” to the name to return a list of all values where the constraints are satisfied, starting with the first or “nth”.
default (int, float, str, or list) – The value to return if the key is not found.
- Returns:
If a name is provided that ends in a plus, the returned value will be the list of all values of the selected key, or else [default] if the list would be empty or the key would raise an error.
Otherwise, the returned value is that of the key if present, or default if it is not.
- Return type:
int, float, str, or list
- Raises:
IndexError – If any numeric component of the key is out of range.
KeyError – If the parameter name is not present in the label (or the section of the label defined by after_name and after_value), or if the key format is unrecognized.
TypeError – If the key is not a recognized type or contains a component that is not of a recognized type.
ValueError – If no identified parameter equals value or if no occurrence of after_name equals after_value.
- items(pattern=None, unique=True)[source]
Iterator over the (key, value) pairs in the label of this VicarImage.
- Parameters:
pattern (str or re.Pattern, optional) – Regular expression that can be used to filter the label parameter names.
unique (bool, optional) – True to return unique keys, in which non-unique names are replaced by tuples (name, occurrence). If False, all keys are name strings, and a name may appear multiple times.
- Returns:
Tuples (name, value) of the matching parameter names within this label, in order.
- Return type:
iterator
- keys(pattern=None)[source]
Iterator over the keys in the label of this VicarImage. The key is the parameter name if it is unique or (name, occurrence number) otherwise.
- Parameters:
pattern (str or re.Pattern, optional) – Regular expression that can be used to filter the label parameter names.
- Returns:
The parameter keys within this label, in order. Each key is the parameter name if it is unique or (name, occurrence number) otherwise.
- Return type:
list
- property label
The VicarLabel object.
- Returns:
The VicarLabel object.
- Return type:
- names(pattern=None)[source]
Iterator for the VICAR parameter name strings in the label of this VicarImage.
- Parameters:
pattern (str or re.Pattern, optional) – Regular expression that can be used to filter the label parameter names.
- Returns:
The matching parameter names within this label, in order.
- Return type:
list
- property prefix
The image prefix object.
- Returns:
The image prefix as a 2-dimensional array.
- Return type:
np.ndarray
- property prefix2d
The image prefix as a 2-D array.
- Returns:
The image prefix as a 2-dimensional array.
- Return type:
np.ndarray
- Raises:
VicarError – If the prefix array has more than two dimensions.
- property prefix3d
The image prefix as a 3-D array.
- Returns:
The image prefix as a 3-dimensional array.
- Return type:
np.ndarray
- property prefix_2d
The image prefix as a 2-D array; DEPRECATED name.
- Returns:
The image prefix as a 2-dimensional array.
- Return type:
np.ndarray
- Raises:
VicarError – If the prefix array has more than two dimensions.
- property prefix_3d
The image prefix as a 3-D array; DEPRECATED name.
- Returns:
The image prefix as a 2-dimensional array.
- Return type:
np.ndarray
- values(pattern=None)[source]
Iterator over the values in the label of this VicarImage.
- Parameters:
pattern (str or re.Pattern, optional) – Regular expression that can be used to filter the label parameter names.
- Returns:
The values of the matching parameters within this label, in order.
- Return type:
iterator
- class vicar.VicarLabel(source=None, strict=True)[source]
Bases:
objectClass to support accessing, reading, modifying, and writing VICAR labels.
Properties:
filepath: The file path associated with this VicarLabel.
Core Methods:
append: Append one or more parameters to the end of this label.
arg: The index of a parameter name within this label.
args: Iterator over the numeric indices of the parameters in this label.
as_string: A string representing all or part of this label.
copy: An independent (deep) copy of this VicarLabel.
export: Returns a label parameter string of the form NAME=VALUE.
from_file: Construct a VicarLabel object from the content of a VICAR data file.
get: Retrieve a label parameter value or return a default.
insert: Insert one or more parameters into this label.
items: Iterator over the (name, value) tuples in this label.
keys: Iterator over the parameter names in this label as unique keys.
name_value_str: Returns a label parameter string of the form NAME=VALUE.
names: Iterator over the parameter names in this label.
read_label: Read the label string(s) from a file.
reorder: Reorder the parameters in this label.
value_str: Formats a label parameter value.
values: Iterator over the parameter values in this label.
write_label: Write this label into a data file, replacing an existing label.
Python Syntax Support Methods:
__contains__: Enables “name in label” syntax.
__delitem__: Enables “del label[name]” syntax.
__eq__: Enables “a == b”, the test of whether two labels are equal.
__getitem__: Enables “label[name]” dictionary-like syntax.
__iter__: Enables “for key in label:” syntax.
__len__: Enables “len(label)”, the number of parameters in the given VicarLabel.
__repr__: Enables “repr(label)”, similar to the “str(label)”, but with the class name included.
__setitem__: Enables “label[name] = value” dictionary-like syntax.
__str__: Enables “str(label)”, returning a string representing the content of a label.
Notes About Dictionary Keys:
When using dictionary-like syntax to reference a parameter in a VICAR label, a rich set of options are available. For example, if label is a VicarLabel object, then:
label[n] where n is an integer refers to the “nth” parameter in the label. n can be positive or negative.
label[name] where name is a string refers to the first occurrence in the label of a parameter with this name.
label[name,n] refers to the “nth” occurrence in the label of a parameter with this name. n can be positive or negative.
label[name, after] where both items are strings refers to the first occurrence of parameter name after the first occurrence of parameter after and before the second occurrence of after.
label[name, after, value] refers to the first occurrence of parameter name after the first location where after equals value and before the next occurrence of after.
The last two options make it easy to reference a VICAR label parameter that is repeated. For example, “label[‘DAT_TIM’, ‘TASK’, ‘COPY’]” uniquely identifies the occurrence of DAT_TIM applicable to TASK=’COPY’ when there might be other TASK sections of the label containing other values of DAT_TIM.
Append a “+” to name to expand upon the function’s behavior. With “get” operations, a list is returned identifying all of the occurrences of the selected name rather than just the first or “nth”. With “set” operations, a new occurrence of name is inserted into the label even if the a parameter of the given name is already present.
Notes About VICAR Label Formatting Hints:
Formatting hints can be included wherever a VICAR parameter value is specified. When defining label parameters using a list of tuples, use (name, value, hints…) instead of (name, value). Elsewhere, simply replace the value by a tuple (value, hints…).
Hints can be specified using up to four items:
([format][[[, name_blanks], val_blanks], sep_blanks])
where:
format is a format string, e.g., “%+7d” or “%7.3f”.
name_blanks is the number of blank characters after the name and before the equal sign; zero by default.
val_blanks is the number of blank characters after the equal sign and before the value; zero by default.
sep_blanks is the number of blanks after the value and before the next label parameter or the label’s end; two by default.
Note the use of square brackets in the tuple expression above. If the first hint value is a string, it is interpreted as format; otherwise, the format is unspecified. After the optional format, values are interpreted as numbers of blanks. If only one int is provided, it defines sep_blanks, with val_blanks and name_blanks set to zero. If two trailing ints are provided, they define val_blanks and sep_blanks, with name_blanks set to zero.
For example, if the name is “TEXP” and the value is 1.5, this is how hint values are interpreted:
<no hints> = ("", 0, 0, 0) -> "TEXP=1.5 " "%.3f" = ("%.3f", 0, 0, 0) -> "TEXP=1.500 " ("%.3f", 4) = ("%.3f", 0, 0, 4) -> "TEXP=1.500 " ("%.3f", 1, 4) = ("%.3f", 0, 1, 4) -> "TEXP= 1.500 " ("%.3f", 2, 1, 4) = ("%.3f", 2, 1, 4) -> "TEXP = 1.500 " 4 = ("", 0, 0, 4) -> "TEXP=1.5 " (1, 4) = ("", 0, 1, 4) -> "TEXP= 1.5 " (2, 1, 4) = ("", 2, 1, 4) -> "TEXP = 1.5 "
When the parameter value is a list, it is also possible to embed formatting information on an item by item basis. Replace any item value by a tuple:
(item [, format][[, blanks_before], blanks_after])
where:
format is a format string, e.g., “%+07d”, “%12.3e” or “%.4f”.
blanks_before is the number of blanks before the value, after the left parenthesis or comma; zero is the default.
blanks_after is the number of blanks after the value and before the next next comma or the right parenthesis; zero is the default.
Here are some examples of a list with embedded formatting for a parameter named “XY” with a value [7,6]:
[(7, "%+02d"), 6] = [(7, "%+02d", 0, 0), 6] -> "XY=[+07, 6] " [(7, 2), 6] = [(7, "", 0, 2), 6] -> "XY=[7 , 6] " [(7, 1, 2), 6]) = [(7, "", 1, 2), 6] -> "XY=[ 7 , 6] " [(7, "%02d", 2), 6]) = [(7, "%02d", 0, 2), 6] -> "XY=[07 , 6] " [(7, "%02d", 1, 2), 6]) = [(7, "%02d", 1, 2), 6] -> "XY=[ 07 , 6] "
- __contains__(key)[source]
True if the given key can be used to index the VICAR label.
- Parameters:
key (int, str, or tuple) –
The indexing key, interpreted as follows:
int = n: The “nth” parameter in the label. n can be positive or negative.
str = name: The first occurrence in the label of a parameter with this name.
(str, int) = (name, n): The “nth” occurrence in the label of a parameter with this name. n can be positive or negative.
(str, str) = (name, after): The first occurrence of parameter name after the first occurrence of parameter after and before the second occurrence of after.
(str, str, any) = (name, after, value): The first occurrence of parameter name after the first location where after equals value and before the next occurrence of after.
The last two options make it easy to reference a VICAR label parameter that is repeated. For example, “label[‘DAT_TIM’, ‘TASK’, ‘COPY’]” uniquely identifies the occurrence of DAT_TIM applicable to TASK=’COPY’ when there might be other TASK sections of the label containing other values of DAT_TIM.
- Returns:
True if the key is found within this label.
- Return type:
bool
- __delitem__(key)[source]
Delete the value of the VICAR parameter identified by the given key.
- Parameters:
key (int, str, or tuple) –
The indexing key, interpreted as follows:
int = n: The “nth” parameter in the label. n can be positive or negative.
str = name: The first occurrence in the label of a parameter with this name.
(str, int) = (name, n): The “nth” occurrence in the label of a parameter with this name. n can be positive or negative.
(str, str) = (name, after): The first occurrence of parameter name after the first occurrence of parameter after and before the second occurrence of after.
(str, str, any) = (name, after, value): The first occurrence of parameter name after the first location where after equals value and before the next occurrence of after.
The last two options make it easy to reference a VICAR label parameter that is repeated. For example, “label[‘DAT_TIM’, ‘TASK’, ‘COPY’]” uniquely identifies the occurrence of DAT_TIM applicable to TASK=’COPY’ when there might be other TASK sections of the label containing other values of DAT_TIM.
Append a “+” to name to delete all of the label parameters whose names match the constraints, starting with the first or “nth”.
- Raises:
IndexError – If any numeric component of the key is out of range.
KeyError – If the parameter name is not present in the label (or the section of the label defined by after_name and after_value), or if the key format is unrecognized.
TypeError – If the key is not a recognized type or contains a component that is not of a recognized type.
ValueError – If no identified parameter equals value or if no occurrence of after_name equals after_value.
- __eq__(other)[source]
VicarLabels are equal if they have the same parameter names in the same order. Formatting and filepath are ignored.
VicarLabels are equal if their parameters and values are all the same; formatting hints need not be the same.
- Parameters:
other (VicarLabel) – Second VicarLabel to compare with this.
- Returns:
True if the names and values are equal.
- Return type:
bool
- __getitem__(key)[source]
Retrieve the value or values of the VICAR parameter defined by key, using various indexing options.
- Parameters:
key (int, name, or tuple) –
The indexing key, interpreted as follows:
int = n: The “nth” parameter in the label. n can be positive or negative.
str = name: The first occurrence in the label of a parameter with this name.
(str, int) = (name, n): The “nth” occurrence in the label of a parameter with this name. n can be positive or negative.
(str, str) = (name, after): The first occurrence of parameter name after the first occurrence of parameter after and before the second occurrence of after.
(str, str, any) = (name, after, value): The first occurrence of parameter name after the first location where after equals value and before the next occurrence of after.
The last two options make it easy to reference a VICAR label parameter that is repeated. For example, “label[‘DAT_TIM’, ‘TASK’, ‘COPY’]” uniquely identifies the occurrence of DAT_TIM applicable to TASK=’COPY’ when there might be other TASK sections of the label containing other values of DAT_TIM.
Append a “+” to the name to return a list of all values where the constraints are satisfied, starting with the first or “nth”.
- Returns:
If key contains a name ending in “+”, this is the list of values of the matching parameters, starting with the “nth”. Otherwise, it is the single matching value.
- Return type:
int, float, string, or list
- Raises:
IndexError – If any numeric component of the key is out of range.
KeyError – If the parameter name is not present in the label (or the section of the label defined by after_name and after_value), or if the key format is unrecognized.
TypeError – If the key is not a recognized type or contains a component that is not of a recognized type.
ValueError – If no identified parameter equals value or if no occurrence of after_name equals after_value.
- __init__(source=None, strict=True)[source]
Constructor for a VicarLabel.
- Parameters:
source (file, FCPath, Path, str, None, dict, or list) –
A representation of a VICAR label:
file: The label string is read from the given, open file.
FCPath or Path: The label string is read from the referenced file.
str: First, a check is performed to see if it is path to an existing file. If so, the label is read from that file; otherwise, the string is itself interpreted as a VICAR label string.
None: The returned VicarLabel only contains the required parameters with their default values.
dict: The label parameters are the names of the dictionary keys, given in the order they were entered into the dictionary. Each dictionary value is either the VICAR parameter value or a tuple(value, formatting hints).
list: The label is derived from the given sequence of (name, value) or (name, value, formatting hints) tuples.
See
Notesfor details about formatting hints.strict (bool, optional) –
True (the default) to require strict conformance to the VICAR standard; False for a looser version of the standard. The standard is described here:
When strict is False:
names can exceed 32 characters and contain lower case letters.
string values need not be pure 7-bit ASCII.
lists can contain a mixture of types.
lists can be empty.
- Raises:
OSError – If the source is given as a file path that cannot be read.
TypeError – If the source is an unrecognized type or contains an unrecognized type.
VicarError – If the source violates the VICAR standard or a required VICAR parameter has an invalid value.
Notes
Formatting hints can be included wherever a VICAR parameter value is specified. When defining label parameters using a list of tuples, use (name, value, hints…) instead of (name, value). Elsewhere, simply replace the value by a tuple (value, hints…).
Hints can be specified using up to four items:
([format][[[, name_blanks], val_blanks], sep_blanks])
where:
format is a format string, e.g., “%+7d” or “%7.3f”.
name_blanks is the number of blank characters after the name and before the equal sign; zero by default.
val_blanks is the number of blank characters after the equal sign and before the value; zero by default.
sep_blanks is the number of blanks after the value and before the next label parameter or the label’s end; two by default.
Note the use of square brackets in the tuple expression above. If the first hint value is a string, it is interpreted as format; otherwise, the format is unspecified. After the optional format, values are interpreted as numbers of blanks. If only one int is provided, it defines sep_blanks, with val_blanks and name_blanks set to zero. If two trailing ints are provided, they define val_blanks and sep_blanks, with name_blanks set to zero.
For example, if the name is “TEXP” and the value is 1.5, this is how hint values are interpreted:
<no hints> = ("", 0, 0, 0) -> "TEXP=1.5 " "%.3f" = ("%.3f", 0, 0, 0) -> "TEXP=1.500 " ("%.3f", 4) = ("%.3f", 0, 0, 4) -> "TEXP=1.500 " ("%.3f", 1, 4) = ("%.3f", 0, 1, 4) -> "TEXP= 1.500 " ("%.3f", 2, 1, 4) = ("%.3f", 2, 1, 4) -> "TEXP = 1.500 " 4 = ("", 0, 0, 4) -> "TEXP=1.5 " (1, 4) = ("", 0, 1, 4) -> "TEXP= 1.5 " (2, 1, 4) = ("", 2, 1, 4) -> "TEXP = 1.5 "
When the parameter value is a list, it is also possible to embed formatting information on an item by item basis. Replace any item value by a tuple:
(item [, format][[, blanks_before], blanks_after])
where:
format is a format string, e.g., “%+07d”, “%12.3e” or “%.4f”.
blanks_before is the number of blanks before the value, after the left parenthesis or comma; zero is the default.
blanks_after is the number of blanks after the value and before the next comma or the right parenthesis; zero is the default.
Here are some examples of a list with embedded formatting for a parameter named “XY” with a value [7,6]:
[(7, "%+02d"), 6] = [(7, "%+02d", 0, 0), 6] -> "XY=[+07, 6] " [(7, 2), 6] = [(7, "", 0, 2), 6] -> "XY=[7 , 6] " [(7, 1, 2), 6]) = [(7, "", 1, 2), 6] -> "XY=[ 7 , 6] " [(7, "%02d", 2), 6]) = [(7, "%02d", 0, 2), 6] -> "XY=[07 , 6] " [(7, "%02d", 1, 2), 6]) = [(7, "%02d", 1, 2), 6] -> "XY=[ 07 , 6] "
- __iter__()[source]
Iterator over the unique names or (name, occurrence) pairs in the label.
- Returns:
An iterator over the parameter keys within this label, in order. The key is the parameter name if it is unique or (name, occurrence number) otherwise.
- Return type:
iterator
- __len__()[source]
The number of keywords in the VICAR label.
- Returns:
Number of keywords.
- Return type:
int
- __setitem__(key, value)[source]
Set the value of the VICAR parameter defined by the given key; define a new parameter name and value if necessary.
- Parameters:
key (int, str, or tuple) –
The indexing key, interpreted as follows:
int = n: The “nth” parameter in the label. n can be positive or negative.
str = name: The first occurrence in the label of a parameter with this name.
(str, int) = (name, n): The “nth” occurrence in the label of a parameter with this name. n can be positive or negative.
(str, str) = (name, after): The first occurrence of parameter name after the first occurrence of parameter after and before the second occurrence of after.
(str, str, any) = (name, after, value): The first occurrence of parameter name after the first location where after equals value and before the next occurrence of after.
The last two options make it easy to reference a VICAR label parameter that is repeated. For example, “label[‘DAT_TIM’, ‘TASK’, ‘COPY’]” uniquely identifies the occurrence of DAT_TIM applicable to TASK=’COPY’ when there might be other TASK sections of the label containing other values of DAT_TIM.
Append a “+” to the name to force a new occurrence of the key to be inserted, even if the key already exists.
value (int, float, string, list, or tuple) –
Value to assign to the indexed entry in the label.
Optional formatting can be included if a user wants additional control over how this value will be formatted in the label string will be formatted, by replacing the value with a tuple (value, hints…). See
Notesfor details about formatting hints.
- Raises:
IndexError – If any numeric component of the key is out of range.
KeyError – If the parameter name is not present in the label (or the section of the label defined by after_name and after_value), or if the key format is unrecognized.
TypeError – If the key is not a recognized type or contains a component that is not of a recognized type.
ValueError – If no identified parameter equals value or if no occurrence of after_name equals after_value.
Notes
Formatting hints can be included wherever a VICAR parameter value is specified; simply replace the value by a tuple (value, hints…).
Hints can be specified using up to four items:
([format][[[, name_blanks], val_blanks], sep_blanks])
where:
format is a format string, e.g., “%+7d” or “%7.3f”.
name_blanks is the number of blank characters after the name and before the equal sign; zero by default.
val_blanks is the number of blank characters after the equal sign and before the value; zero by default.
sep_blanks is the number of blanks after the value and before the next label parameter or the label’s end; two by default.
Note the use of square brackets in the tuple expression above. If the first hint value is a string, it is interpreted as format; otherwise, the format is unspecified. After the optional format, values are interpreted as numbers of blanks. If only one int is provided, it defines sep_blanks, with val_blanks and name_blanks set to zero. If two trailing ints are provided, they define val_blanks and sep_blanks, with name_blanks set to zero.
For example, if the name is “TEXP” and the value is 1.5, this is how hint values are interpreted:
<no hints> = ("", 0, 0, 0) -> "TEXP=1.5 " "%.3f" = ("%.3f", 0, 0, 0) -> "TEXP=1.500 " ("%.3f", 4) = ("%.3f", 0, 0, 4) -> "TEXP=1.500 " ("%.3f", 1, 4) = ("%.3f", 0, 1, 4) -> "TEXP= 1.500 " ("%.3f", 2, 1, 4) = ("%.3f", 2, 1, 4) -> "TEXP = 1.500 " 4 = ("", 0, 0, 4) -> "TEXP=1.5 " (1, 4) = ("", 0, 1, 4) -> "TEXP= 1.5 " (2, 1, 4) = ("", 2, 1, 4) -> "TEXP = 1.5 "
When the parameter value is a list, it is also possible to embed formatting information on an item by item basis. Replace any item value by a tuple:
(item [, format][[, blanks_before], blanks_after])
where:
format is a format string, e.g., “%+07d”, “%12.3e” or “%.4f”.
blanks_before is the number of blanks before the value, after the left parenthesis or comma; zero is the default.
blanks_after is the number of blanks after the value and before the next comma or the right parenthesis; zero is the default.
Here are some examples of a list with embedded formatting for a parameter named “XY” with a value [7,6]:
[(7, "%+02d"), 6] = [(7, "%+02d", 0, 0), 6] -> "XY=[+07, 6] " [(7, 2), 6] = [(7, "", 0, 2), 6] -> "XY=[7 , 6] " [(7, 1, 2), 6]) = [(7, "", 1, 2), 6] -> "XY=[ 7 , 6] " [(7, "%02d", 2), 6]) = [(7, "%02d", 0, 2), 6] -> "XY=[07 , 6] " [(7, "%02d", 1, 2), 6]) = [(7, "%02d", 1, 2), 6] -> "XY=[ 07 , 6] "
- append(source)[source]
Append the additional content to the end of this label.
- Parameters:
source (file, FCPath, Path, str, None, dict, list, or tuple) –
A representation of VICAR label content:
file: The label string is read from the given, open file.
FCPath or Path: The label string is read from the referenced file.
str: First, a check is performed to see if it is path to an existing file. If so, the label is read from that file; otherwise, the string is itself interpreted as a VICAR label string.
None: The returned VicarLabel only contains the required parameters with their default values.
dict: The label parameters are the names of the dictionary keys, given in the order they were entered into the dictionary. Each dictionary value is either the VICAR parameter value or a tuple(value, formatting hints).
list: The label is derived from the given sequence of (name, value) or (name, value, formatting hints) tuples.
tuple: A single parameter defined by (name, value) or (name, value, formatting hints).
See
Notesfor details about formatting hints.- Raises:
OSError – If the source is given as a file path that cannot be read.
TypeError – If the source is an unrecognized type or contains an unrecognized type.
VicarError – If the source violates the VICAR standard or a required VICAR parameter has an invalid value.
Notes
Formatting hints can be included wherever a VICAR parameter value is specified. When defining label parameters using a list of tuples, use (name, value, hints…) instead of (name, value). Elsewhere, simply replace the value by a tuple (value, hints…).
Hints can be specified using up to four items:
([format][[[, name_blanks], val_blanks], sep_blanks])
where:
format is a format string, e.g., “%+7d” or “%7.3f”.
name_blanks is the number of blank characters after the name and before the equal sign; zero by default.
val_blanks is the number of blank characters after the equal sign and before the value; zero by default.
sep_blanks is the number of blanks after the value and before the next label parameter or the label’s end; two by default.
Note the use of square brackets in the tuple expression above. If the first hint value is a string, it is interpreted as format; otherwise, the format is unspecified. After the optional format, values are interpreted as numbers of blanks. If only one int is provided, it defines sep_blanks, with val_blanks and name_blanks set to zero. If two trailing ints are provided, they define val_blanks and sep_blanks, with name_blanks set to zero.
For example, if the name is “TEXP” and the value is 1.5, this is how hint values are interpreted:
<no hints> = ("", 0, 0, 0) -> "TEXP=1.5 " "%.3f" = ("%.3f", 0, 0, 0) -> "TEXP=1.500 " ("%.3f", 4) = ("%.3f", 0, 0, 4) -> "TEXP=1.500 " ("%.3f", 1, 4) = ("%.3f", 0, 1, 4) -> "TEXP= 1.500 " ("%.3f", 2, 1, 4) = ("%.3f", 2, 1, 4) -> "TEXP = 1.500 " 4 = ("", 0, 0, 4) -> "TEXP=1.5 " (1, 4) = ("", 0, 1, 4) -> "TEXP= 1.5 " (2, 1, 4) = ("", 2, 1, 4) -> "TEXP = 1.5 "
When the parameter value is a list, it is also possible to embed formatting information on an item by item basis. Replace any item value by a tuple:
(item [, format][[, blanks_before], blanks_after])
where:
format is a format string, e.g., “%+07d”, “%12.3e” or “%.4f”.
blanks_before is the number of blanks before the value, after the left parenthesis or comma; zero is the default.
blanks_after is the number of blanks after the value and before the next comma or the right parenthesis; zero is the default.
Here are some examples of a list with embedded formatting for a parameter named “XY” with a value [7,6]:
[(7, "%+02d"), 6] = [(7, "%+02d", 0, 0), 6] -> "XY=[+07, 6] " [(7, 2), 6] = [(7, "", 0, 2), 6] -> "XY=[7 , 6] " [(7, 1, 2), 6]) = [(7, "", 1, 2), 6] -> "XY=[ 7 , 6] " [(7, "%02d", 2), 6]) = [(7, "%02d", 0, 2), 6] -> "XY=[07 , 6] " [(7, "%02d", 1, 2), 6]) = [(7, "%02d", 1, 2), 6] -> "XY=[ 07 , 6] "
- arg(key, value=None)[source]
The numerical index or indices of the keyed item in the VICAR label.
- Parameters:
key (int, name, or tuple) –
The indexing key, interpreted as follows:
int = n: The “nth” parameter in the label. n can be positive or negative.
str = name: The first occurrence in the label of a parameter with this name.
(str, int) = (name, n): The “nth” occurrence in the label of a parameter with this name. n can be positive or negative.
(str, str) = (name, after): The first occurrence of parameter name after the first occurrence of parameter after and before the second occurrence of after.
(str, str, any) = (name, after, value): The first occurrence of parameter name after the first location where after equals value and before the next occurrence of after.
The last two options make it easy to reference a VICAR label parameter that is repeated. For example, “label[‘DAT_TIM’, ‘TASK’, ‘COPY’]” uniquely identifies the occurrence of DAT_TIM applicable to TASK=’COPY’ when there might be other TASK sections of the label containing other values of DAT_TIM.
Append a “+” to the name to return a list of all indices where the constraints are satisfied, starting with the first or “nth”.
value (int, float, or string, optional) – If provided, the identified parameter must equal this value. For an integer key, if the indexed parameter does not have this value, ValueError is raised. For any key involving a name, values of the named parameter that do not match value are skipped over until the one(s) with the correct value are found.
- Returns:
The index or list of indices that identify matching parameters. If the key contains a name ending in “+”, this is a list starting with the “nth” occurrence; otherwise, it is a single int.
- Return type:
int or list[int]
- Raises:
IndexError – If any numeric component of the key is out of range.
KeyError – If the parameter name is not present in the label (or the section of the label defined by after_name and after_value), or if the key format is unrecognized.
TypeError – If the key is not a recognized type or contains a component that is not of a recognized type.
ValueError – If no identified parameter equals value or if no occurrence of after_name equals after_value.
- args(pattern=None)[source]
Iterator over the numerical indices of the keywords.
- Parameters:
pattern (str or re.Pattern, optional) – Regular expression that can be used to filter the label parameter names.
- Returns:
The indices of the matching parameter names within this label, in order.
- Return type:
iterator
- as_string(start=0, stop=None, sep='')[source]
The content of this label as a string.
- Parameters:
start (int, optional) – Index or key of the first parameter to include in the string.
stop (int, optional) – Index or key just after the last parameter to include in the string.
sep (str, optional) – Optional characters to insert before a second LBLSIZE. For example, use “n” to create a string with a line break before any extension label.
- Returns:
A label string compliant with the VICAR standard.
- Return type:
str
- export(resize=True)[source]
Export this VicarLabel to text strings.
- Parameters:
resize (bool, optional) – If True, LBLSIZE will be modified to accommodate the new content. Otherwise, the current value of LBLSIZE will be preserved and any overflow content will be placed into an end-of-file label.
- Returns:
A tuple containing:
str: The VICAR label at the top of the file, as constrained by the internal values of LBLSIZE and RECSIZE. The string is padded with null characters to the full length specified by LBLSIZE.
str: The VICAR end-of-file label; empty if all the label content fits within the specified LBLSIZE.
- Return type:
(str, str)
Note
The returned strings must be encoded as “latin1” bytes before writing them into a data file.
- property filepath
The file path associated with this VicarLabel.
- Returns:
The FCPath if this object is associated with a file; None otherwise.
- Return type:
FCPath or None
- static from_file(filepath)[source]
A new VicarLabel object derived from the given VICAR data file.
- Parameters:
filepath (FCPath, Path, or str) – Path to a VICAR data file.
- Returns:
VicarLabel object read from file.
- Return type:
- get(key, default)[source]
Retrieve the value of the VICAR parameter defined by the given key, using various indexing options.
If the key is not found, return a specified default value.
- Parameters:
key (int, str, or tuple) –
The indexing key, interpreted as follows:
int = n: The “nth” parameter in the label. n can be positive or negative.
str = name: The first occurrence in the label of a parameter with this name.
(str, int) = (name, n): The “nth” occurrence in the label of a parameter with this name. n can be positive or negative.
(str, str) = (name, after): The first occurrence of parameter name after the first occurrence of parameter after and before the second occurrence of after.
(str, str, any) = (name, after, value): The first occurrence of parameter name after the first location where after equals value and before the next occurrence of after.
The last two options make it easy to reference a VICAR label parameter that is repeated. For example, “label[‘DAT_TIM’, ‘TASK’, ‘COPY’]” uniquely identifies the occurrence of DAT_TIM applicable to TASK=’COPY’ when there might be other TASK sections of the label containing other values of DAT_TIM.
Append a “+” to the name to return a list of all values where the constraints are satisfied, starting with the first or “nth”.
default (int, float, str, or list) – The value to return if the key is not found.
- Returns:
If a name is provided that ends in a plus, the returned value will be the list of all values of the selected key, or else [default] if the key would raise an error.
Otherwise, the returned value is that of the key if present, or default if it is not.
- Return type:
int, float, str, or list
- Raises:
IndexError – If any numeric component of the key is out of range.
KeyError – If the parameter name is not present in the label (or the section of the label defined by after_name and after_value), or if the key format is unrecognized.
TypeError – If the key is not a recognized type or contains a component that is not of a recognized type.
ValueError – If no identified parameter equals value or if no occurrence of after_name equals after_value.
- insert(source, indx)[source]
Insert the given content into this label at the specified index.
- Parameters:
source (file, FCPath, Path, str, dict, list, or tuple) –
A representation of VICAR label content:
file: The label string is read from the given, open file.
FCPath or Path: The label string is read from the referenced file.
str: First, a check is performed to see if it is path to an existing file. If so, the label is read from that file; otherwise, the string is itself interpreted as a VICAR label string.
dict: The label parameters are the names of the dictionary keys, given in the order they were entered into the dictionary. Each dictionary value is either the VICAR parameter value or a tuple(value, formatting hints).
list: The label is derived from the given sequence of (name, value) or (name, value, formatting hints) tuples.
tuple: A single parameter defined by (name, value) or (name, value, formatting hints).
See
Notesfor details about formatting hints.indx (int) – The integer index defining the location at which to insert the new content. If the index is non-negative, the new new content will begin at this index. If negative, the new content will end just before this index. To append, to the label, use indx = len(self).
- Raises:
OSError – If the source is given as a file path that cannot be read.
TypeError – If the source is an unrecognized type or contains an unrecognized type.
VicarError – If the source violates the VICAR standard or a required VICAR parameter has an invalid value.
Notes
Formatting hints can be included wherever a VICAR parameter value is specified. When defining label parameters using a list of tuples, use (name, value, hints…) instead of (name, value). Elsewhere, simply replace the value by a tuple (value, hints…).
Hints can be specified using up to four items:
([format][[[, name_blanks], val_blanks], sep_blanks])
where:
format is a format string, e.g., “%+7d” or “%7.3f”.
name_blanks is the number of blank characters after the name and before the equal sign; zero by default.
val_blanks is the number of blank characters after the equal sign and before the value; zero by default.
sep_blanks is the number of blanks after the value and before the next label parameter or the label’s end; two by default.
Note the use of square brackets in the tuple expression above. If the first hint value is a string, it is interpreted as format; otherwise, the format is unspecified. After the optional format, values are interpreted as numbers of blanks. If only one int is provided, it defines sep_blanks, with val_blanks and name_blanks set to zero. If two trailing ints are provided, they define val_blanks and sep_blanks, with name_blanks set to zero.
For example, if the name is “TEXP” and the value is 1.5, this is how hint values are interpreted:
<no hints> = ("", 0, 0, 0) -> "TEXP=1.5 " "%.3f" = ("%.3f", 0, 0, 0) -> "TEXP=1.500 " ("%.3f", 4) = ("%.3f", 0, 0, 4) -> "TEXP=1.500 " ("%.3f", 1, 4) = ("%.3f", 0, 1, 4) -> "TEXP= 1.500 " ("%.3f", 2, 1, 4) = ("%.3f", 2, 1, 4) -> "TEXP = 1.500 " 4 = ("", 0, 0, 4) -> "TEXP=1.5 " (1, 4) = ("", 0, 1, 4) -> "TEXP= 1.5 " (2, 1, 4) = ("", 2, 1, 4) -> "TEXP = 1.5 "
When the parameter value is a list, it is also possible to embed formatting information on an item by item basis. Replace any item value by a tuple:
(item [, format][[, blanks_before], blanks_after])
where:
format is a format string, e.g., “%+07d”, “%12.3e” or “%.4f”.
blanks_before is the number of blanks before the value, after the left parenthesis or comma; zero is the default.
blanks_after is the number of blanks after the value and before the next comma or the right parenthesis; zero is the default.
Here are some examples of a list with embedded formatting for a parameter named “XY” with a value [7,6]:
[(7, "%+02d"), 6] = [(7, "%+02d", 0, 0), 6] -> "XY=[+07, 6] " [(7, 2), 6] = [(7, "", 0, 2), 6] -> "XY=[7 , 6] " [(7, 1, 2), 6]) = [(7, "", 1, 2), 6] -> "XY=[ 7 , 6] " [(7, "%02d", 2), 6]) = [(7, "%02d", 0, 2), 6] -> "XY=[07 , 6] " [(7, "%02d", 1, 2), 6]) = [(7, "%02d", 1, 2), 6] -> "XY=[ 07 , 6] "
- items(pattern=None, unique=True)[source]
Iterator over the (key, value) pairs in this label.
- Parameters:
pattern (str or re.Pattern, optional) – Regular expression that can be used to filter the label parameter names.
unique (bool, optional) – True to return unique keys, in which non-unique names are replaced by tuples (name, occurrence). If False, all keys are name strings, and a name may appear multiple times.
- Returns:
The tuples (name, value) of the matching parameter names within this label, in order.
- Return type:
iterator
- keys(pattern=None)[source]
Iterator over the keys of the parameters within this label.
- Parameters:
pattern (str or re.Pattern, optional) – Regular expression that can be used to filter the label parameter names.
- Returns:
The list of the parameter keys within this label, in order. The key is the parameter name if it is unique or (name, occurrence number) otherwise.
- Return type:
list
- name_value_str(key, pad=True)[source]
Convert one entry in the dictionary to a string of the form “NAME=VALUE”.
- Parameters:
key (int, str, or tuple) –
The indexing key, interpreted as follows:
int = n: The “nth” parameter in the label. n can be positive or negative.
str = name: The first occurrence in the label of a parameter with this name.
(str, int) = (name, n): The “nth” occurrence in the label of a parameter with this name. n can be positive or negative.
(str, str) = (name, after): The first occurrence of parameter name after the first occurrence of parameter after and before the second occurrence of after.
(str, str, any) = (name, after, value): The first occurrence of parameter name after the first location where after equals value and before the next occurrence of after.
The last two options make it easy to reference a VICAR label parameter that is repeated. For example, “label[‘DAT_TIM’, ‘TASK’, ‘COPY’]” uniquely identifies the occurrence of DAT_TIM applicable to TASK=’COPY’ when there might be other TASK sections of the label containing other values of DAT_TIM.
pad (bool, optional) – If True, the returned string will end with at least one blank character.
- Returns:
A “NAME=VALUE” string compliant with the VICAR standard.
- Return type:
str
- Raises:
IndexError – If any numeric component of the key is out of range.
KeyError – If the parameter name is not present in the label (or the section of the label defined by after_name and after_value), or if the key format is unrecognized.
TypeError – If the key is not a recognized type or contains a component that is not of a recognized type.
ValueError – If no identified parameter equals value or if no occurrence of after_name equals after_value.
- names(pattern=None)[source]
Iterator over the names in this label.
- Parameters:
pattern (str or re.Pattern, optional) – Regular expression that can be used to filter the label parameter names.
- Returns:
The list of the matching parameter names within this label, in order.
- Return type:
list
- static read_label(source, _extra=False)[source]
The VICAR label string from the specified data file.
If an EOL label is present, the content of the extension label is appended to the returned string. This can be recognized by a second occurrence of the LBLSIZE parameter.
- Parameters:
source (str, FCPath, Path, or file) – A path to a VICAR data file or else a file object already opened for binary read.
_extra (bool, optional) – True to return any extraneous bytes from the end of the data file in addition to the label.
- Returns:
A string or a tuple containing:
str: The VICAR label as a character string, with the EOL label appended if one is present. The EOL label can be recognized by the presence of a second LBLSIZE parameter.
bytes: A bytes object containing any extraneous characters at the end of the file, included if _extra is True.
- Return type:
str or (str, bytes)
- Raises:
OSError – If the referenced file could not be read.
VicarError – If the referenced file does not conform to the VICAR standard.
- reorder(*keys)[source]
Re-order one or more specified parameters inside this object.
- Parameters:
*keys (list[int, name, or tuple]) –
Two or more indexing keys, interpreted as follows:
int = n: The “nth” parameter in the label. n can be positive or negative.
str = name: The first occurrence in the label of a parameter with this name.
(str, int) = (name, n): The “nth” occurrence in the label of a parameter with this name. n can be positive or negative.
(str, str) = (name, after): The first occurrence of parameter name after the first occurrence of parameter after and before the second occurrence of after.
(str, str, any) = (name, after, value): The first occurrence of parameter name after the first location where after equals value and before the next occurrence of after.
The last two options make it easy to reference a VICAR label parameter that is repeated. For example, “label[‘DAT_TIM’, ‘TASK’, ‘COPY’]” uniquely identifies the occurrence of DAT_TIM applicable to TASK=’COPY’ when there might be other TASK sections of the label containing other values of DAT_TIM.
- Raises:
IndexError – If any numeric component of the key is out of range.
KeyError – If the parameter name is not present in the label (or the section of the label defined by after_name and after_value), or if the key format is unrecognized.
TypeError – If the key is not a recognized type or contains a component that is not of a recognized type.
ValueError – If no identified parameter equals value or if no occurrence of after_name equals after_value. Also if an index is duplicated in the new order.
Notes
The first key is left in place, and subsequent keys are positioned after it in the order given. Use “” in front of the first key if you want the listed keys to be first.
- value_str(key)[source]
The value of the given parameter as it will appear in the label.
- Parameters:
key (int, str, or tuple) –
The indexing key, interpreted as follows:
int = n: The “nth” parameter in the label. n can be positive or negative.
str = name: The first occurrence in the label of a parameter with this name.
(str, int) = (name, n): The “nth” occurrence in the label of a parameter with this name. n can be positive or negative.
(str, str) = (name, after): The first occurrence of parameter name after the first occurrence of parameter after and before the second occurrence of after.
(str, str, any) = (name, after, value): The first occurrence of parameter name after the first location where after equals value and before the next occurrence of after.
The last two options make it easy to reference a VICAR label parameter that is repeated. For example, “label[‘DAT_TIM’, ‘TASK’, ‘COPY’]” uniquely identifies the occurrence of DAT_TIM applicable to TASK=’COPY’ when there might be other TASK sections of the label containing other values of DAT_TIM.
- Returns:
- The VICAR-compliant string representing the value of the selected
parameter.
- Return type:
str
- Raises:
IndexError – If any numeric component of the key is out of range.
KeyError – If the parameter name is not present in the label (or the section of the label defined by after_name and after_value), or if the key format is unrecognized.
TypeError – If the key is not a recognized type or contains a component that is not of a recognized type.
ValueError – If no identified parameter equals value or if no occurrence of after_name equals after_value.
- values(pattern=None)[source]
Iterator over the values in this VicarLabel.
- Parameters:
pattern (str or re.Pattern, optional) – Regular expression that can be used to filter the label parameter names.
- Returns:
The values of the matching parameters within this label, in order.
- Return type:
iterator
- write_label(filepath=None)[source]
Replace the label in the selected VICAR file with this label content.
- Parameters:
filepath (FCPath, Path, or str, optional) – Optional path of the existing file to write. If not provided, the value of this object’s filepath attribute is used.
Note
This method modifies the file without first creating a backup, so it should be used with caution.