ahds package

ahds

This module provides a simple entry-point for using the underlying functionality through the AmiraFile class which automatically handles both AmiraMesh and HxSurface files. An AmiraFile is also a Block subclass with special attributes meta - for metadata not explicitly provided in the file (such as header_length), header - for the parse header and data_streams with the actual data stream data.

The only required argument is the name of the file to be read. By default, data streams are loaded but can be turned off (for quick reading) by setting load_stream=False. Additional kwargs are passed to the AmiraHeader class call.

There is a read method which (if data streams have not yet been read) will read the data streams.

An AmiraFile object may be printed to view the hierarchy of entities above or passed to repr to view the instatiation call that represents it.

class ahds.AmiraFile(fn, load_streams=True, *args, **kwargs)[source]

Bases: ahds.core.Block

Main entry point for working with Amira files

read()[source]

Read the data streams if they are not read yet

class ahds.AmiraHeader(fn, load_streams=True, *args, **kwargs)[source]

Bases: ahds.core.Block

Class to encapsulate Amira metadata and accessors to Amira (R) data streams

data_pointers(**kwargs)[source]

The list of data pointers together with a name, data type, dimension, index, format and length

NOTE: deprecated access the data defnitions for each data array through the corresponding attributes eg.: ah.Nodes.Coordinates instead of ah.data_pointers.data_pointer_1 ah.Tetrahedra.Nodes instead of ah.data_pointers.data_pointer_2 etc.

definitions(**kwargs)[source]

Definitions consist of a key-value pair specified just after the designation preceded by the key-word ‘define’

NOTE: this property is deprecated access the corresponding attributes directly eg. ah.Nodes instead of ah.definitions.Nodes or ah.Tetrahedra instead of ah.defintions.Tetrahedra

designation(**kwargs)[source]

Designation of the Amira file defined in the first row

Designations consist of some or all of the following data:

  • filetype e.g. AmiraMesh or HyperSurface
  • dimensions e.g. 3D
  • format e.g. BINARY-LITTLE-ENDIAN
  • version e.g. 2.1
  • extra format e.g. <hxsurface>

NOTE: this property is deprecated use the corresponding attributes of the AmiraHeader instead to access the above informations

classmethod from_file(**kwargs)[source]

Deprecated classmethod

load()[source]

Public loading method

ahds.grammar module

grammar

We define an EBNF grammar for Amira (R) headers to extract all metadata. In addition to that, we also define how HxSurface files are structured.

This module also includes several helper functions that use the grammar resources:

  • the get_header function returns only the header up to the first data stream; data is returned as a decoded string (UTF-8);
  • the parse_header function applies the grammar to return a nested set of Python primitives to be transformed into an AmiraHeader object;
  • the get_parsed_data function transparently applied both above functions given the Amira (R) filename
ahds.grammar.detect_format(fn, format_bytes=50, verbose=False, *args, **kwargs)[source]

Detect Amira (R) file format (AmiraMesh/Avizo or HyperSurface)

Parameters:
  • fn (str) – file name
  • format_bytes (int) – number of bytes in which to search for the format [default: 50]
  • verbose (bool) – verbose (default) or not
Return str file_format:
 

either AmiraMesh or HyperSurface

ahds.grammar.get_header(fn, file_format, header_bytes=20000, verbose=True, *args, **kwargs)[source]

Apply rules for detecting the boundary of the header

Parameters:
  • fn (str) – file name
  • file_format (str) – either AmiraMesh or HyperSurface
  • header_bytes (int) – number of bytes in which to search for the header [default: 20000]
Return str data:
 

the header as per the file_format

ahds.grammar.get_parsed_data(fn, *args, **kwargs)[source]

All above functions as a single function

Parameters:fn (str) – file name
Return tuple(list,int) parsed_data,header_length:
 structured metadata and total number of header bytes
ahds.grammar.parse_header(data, verbose=False, *args, **kwargs)[source]

Parse the data using the grammar specified in this module

Parameters:data (str) – delimited data to be parsed for metadata
Return list parsed_data:
 structured metadata

ahds.header module

ahds.data_stream module

data_stream

Classes that define data streams (DataList) in Amira (R) files

There are two main types of data streams:

  • AmiraMeshDataStream is for AmiraMesh files
  • AmiraHxSurfaceDataStream is for HxSurface files

Both classes inherit from AmiraDataStream class, which handles common functionality such as:

  • initialisation with the header metadata
  • the get_data method calls each subclass’s _decode method
class ahds.data_stream.AmiraHxSurfaceDataStream(name, header)[source]

Bases: ahds.data_stream.AmiraDataStream

Class that defines an Amira HxSurface data stream

add_attr(attr, value=None, isparent=False)

Add an attribute to this block object

get_data()

Decode and return the stream data in this stream

is_parent

A ListBlock is a parent if it has a Block attribute or if it has list items

load_stream

Reports whether data streams are loaded or not

material_dict

A convenience dictionary of materials indexed by material name

If this is not a Materials ListBlock (name = ‘Material’) then it should return None

move_attr(new_name, name)

Rename an attribute

read()[source]

Extract the data streams from the HxSurface file

class ahds.data_stream.AmiraMeshDataStream(name, header)[source]

Bases: ahds.data_stream.AmiraDataStream

Class that defines an AmiraMesh data stream

add_attr(attr, value=None, isparent=False)

Add an attribute to this block object

get_data()

Decode and return the stream data in this stream

is_parent

A ListBlock is a parent if it has a Block attribute or if it has list items

load_stream

Reports whether data streams are loaded or not

material_dict

A convenience dictionary of materials indexed by material name

If this is not a Materials ListBlock (name = ‘Material’) then it should return None

move_attr(new_name, name)

Rename an attribute

read()[source]

Extract the data streams from the AmiraMesh file

ahds.data_stream.byterle_decoder(data, output_size)[source]

If the C-ext. failed to compile or is unimportable use this slower Python equivalent

Parameters:
  • data (str) – a raw stream of data to be unpacked
  • output_size (int) – the number of items when data is uncompressed
Return np.array output:
 

an array of np.uint8

ahds.data_stream.hxbyterle_decode(data, output_size)

If the C-ext. failed to compile or is unimportable use this slower Python equivalent

Parameters:
  • data (str) – a raw stream of data to be unpacked
  • output_size (int) – the number of items when data is uncompressed
Return np.array output:
 

an array of np.uint8

ahds.data_stream.hxzip_decode(data, output_size)[source]

Decode HxZip data stream

Parameters:
  • data (str) – a raw stream of data to be unpacked
  • output_size (int) – the number of items when data is uncompressed
Return np.array output:
 

an array of np.uint8

ahds.data_stream.set_data_stream(name, header)[source]

Factory function used by AmiraHeader to determine the type of data stream present