c4d.storage.HyperFile – a hyper file class

Hyper files are used to store data in a file. The HyperFile works with the ‘FIFO’ concept. The values will be written and read in the same order.

The following source code is a simple example how to use the HyperFile class:

import c4d, os
from c4d import storage as st

YOUR_IDENT=49545 #choose a personal ident
path = os.path.join("/Users", "Dev", "Desktop", "test.file")

def write(path, key):
    #write
    print path
    hf = st.HyperFile()
    print hf.Open(filename=path, mode=st.GE_WRITE, ident=key)
    bc = c4d.BaseContainer()
    bc[0] = "text"
    bc[1] = "3"
    hf.WriteContainer(bc)
    hf.Close()

def read(path, key):
  #read
  hf = st.HyperFile()
  hf.Open(filename=path, mode=st.GE_READ, ident=key)
  bc = hf.ReadContainer()
  hf.Close()
  print bc[0] #output string 'test'


write(path, YOUR_IDENT) #write file
read(path, YOUR_IDENT) #read file

class c4d.storage.HyperFile

• HyperFile.__init__()

• HyperFile.WriteChar()
• HyperFile.WriteUChar()
• HyperFile.WriteWord()
• HyperFile.WriteUWord()
• HyperFile.WriteInt()
• HyperFile.WriteULong()
• HyperFile.WriteFloat()
• HyperFile.WriteBool()
• HyperFile.WriteTime()
• HyperFile.WriteVector()
• HyperFile.WriteMatrix()
• HyperFile.WriteString()
• HyperFile.WriteFilename()
• HyperFile.WriteImage()
• HyperFile.WriteContainer()
• HyperFile.WriteLLong()
• HyperFile.WriteData()

• HyperFile.ReadChar()
• HyperFile.ReadUChar()
• HyperFile.ReadWord()
• HyperFile.ReadUWord()
• HyperFile.ReadInt()
• HyperFile.ReadULong()
• HyperFile.ReadFloat()
• HyperFile.ReadBool()
• HyperFile.ReadTime()
• HyperFile.ReadVector()
• HyperFile.ReadMatrix()
• HyperFile.ReadString()
• HyperFile.ReadFilename()
• HyperFile.ReadImage()
• HyperFile.ReadContainer()
• HyperFile.ReadLLong()
• HyperFile.ReadData()

• HyperFile.GetError()
• HyperFile.SetError()

• HyperFile.ReadValueHeader()
• HyperFile.SkipValue()

• HyperFile.WriteChunkStart()
• HyperFile.WriteChunkEnd()

• HyperFile.ReadChunkStart()
• HyperFile.ReadChunkEnd()

• HyperFile.SkipToEndChunk()

• HyperFile.GetDocument()
• HyperFile.GetFileVersion()

• HyperFile.Open()
• HyperFile.Close()

Private

• HyperFile.WriteMemory()
• HyperFile.WriteLFloat()
• HyperFile.WriteLVector()
• HyperFile.WriteLMatrix()

• HyperFile.ReadLMatrix()
• HyperFile.ReadLFloat()
• HyperFile.ReadLVector()
• HyperFile.ReadMemory()

Methods

static HyperFile.__init__()

Allocates a hyper file.

Return type:HyperFile Returns:The hyper file.

HyperFile.Open(filename, mode, ident)

Opens the hyper file.

Parameters:

• filename (str) – File to open.
• mode (int) –

  File mode:

  GE_READ	Open the file for reading.
  GE_WRITE	Create a new file for writing. If the file name points to an existing file, it will be overwritten!
  GE_APPEND	Open an existing file for writing and set the position to the end of that file.
  GE_READWRITE	Open the file for both reading and writing.

• ident (int) – File identification.

Return type:

bool

Returns:

True if the hyper file could be opened, otherwise False.

HyperFile.Close()

Closes the hyper file.

Return type:bool Returns:Return True on success.

HyperFile.Open(filename, mode, ident)

Opens the hyper file.

Parameters:

• filename (str) – File to open.
• mode (int) –

  File mode:

  GE_READ	Open the file for reading.
  GE_WRITE	Create a new file for writing. If the file name points to an existing file, it will be overwritten!
  GE_APPEND	Open an existing file for writing and set the position to the end of that file.
  GE_READWRITE	Open the file for both reading and writing.

• ident (int) – File identification.

Return type:

bool

Returns:

True if the hyper file could be closed.

HyperFile.WriteChar(v)

Write a character to the hyperfile.

Parameter:v (int) – A char to write to the hyperfile. Return type:bool Returns:Success of writing the value.

HyperFile.WriteUChar(v)

Write a very short int to the hyperfile.

Parameter:v (int) – The value to write to the hyperfile. Return type:bool Returns:Success of writing the value.

HyperFile.WriteWord(v)

Write a signed short int to the hyperfile.

Parameter:v (int) – The value to write to the hyperfile. Return type:bool Returns:Success of writing the value.

HyperFile.WriteUWord(v)

Write a unsigned short int to the hyperfile.

Parameter:v (int) – The value to write to the hyperfile. Return type:bool Returns:Success of writing the value.

HyperFile.WriteInt(v)

Write an int to the hyperfile.

Parameter:v (int) – The value to write to the hyperfile. Return type:bool Returns:Success of writing the value.

HyperFile.WriteULong(v)

Write an unsigned int to the hyperfile.

Parameter:v (int) – The value to write to the hyperfile. Return type:bool Returns:Success of writing the value.

HyperFile.WriteFloat(v)

Write a real (single precision) value to the hyperfile.

Parameter:v (int) – The value to write to the hyperfile. Return type:bool Returns:Success of writing the value.

HyperFile.WriteBool(v)

Write a bool to the hyperfile.

Parameter:v (bool) – The value to write to the hyperfile. Return type:bool Returns:Success of writing the value.

HyperFile.WriteTime(v)

Write a BaseTime to the hyperfile.

Parameter:v (BaseTime) – The value to write to the hyperfile. Return type:bool Returns:Success of writing the value.

HyperFile.WriteVector(v)

Write a Vector to the hyperfile.

Parameter:v (Vector) – The value to write to the hyperfile. Return type:bool Returns:Success of writing the value.

HyperFile.WriteMatrix(v)

Write a Matrix to the hyperfile.

Parameter:v (Matrix) – The value to write to the hyperfile. Return type:bool Returns:Success of writing the value.

HyperFile.WriteString(v)

Write a string to the hyperfile.

Parameter:v (str) – The value to write to the hyperfile. Return type:bool Returns:Success of writing the value.

HyperFile.WriteFilename(v)

Write a path to the hyperfile.

Parameter:v (str) – The path to write to the hyperfile. Return type:bool Returns:Success of writing the value.

HyperFile.WriteImage(v, format, data[, savebits=SAVEBIT_ALPHA])

Write a filename to the hyperfile.

Note

SAVEBIT_ALPHA is defined in c4d.bitmaps.

Parameters:

• v (BaseBitmap) – The bitmap to write to the file.
• format (int) –

  The image’s file format, stored in c4d.bitmaps:

  FILTER_TIF	TIF
  FILTER_TGA	TGA
  FILTER_BMP	BMP
  FILTER_IFF	IFF
  FILTER_JPG	JPG
  FILTER_PICT	PICT
  FILTER_PSD	PSD
  FILTER_RLA	RLA
  FILTER_RPF	RPF
  FILTER_B3D	B3D
  FILTER_TIF_B3D	TIFF B3D.
  FILTER_AVI	AVI movie
  FILTER_MOVIE	QuickTime movie.
  FILTER_QTVRSAVER_PANORAMA	QTVR panorama
  FILTER_QTVRSAVER_OBJECT	QTVR object
  FILTER_HDR	HDR
  FILTER_PNG	PNG

• data (BaseContainer) –

  Either a container with additional format settings or

  SAVEBIT_ALPHA	Save the alpha channel(s) in the file. (For filter plugins, don’t save an alpha channel if this isn’t set.)
  SAVEBIT_GREYSCALE	Save in grayscale mode.
  SAVEBIT_MULTILAYER	Save multiple layers.
  SAVEBIT_USESELECTEDLAYERS	Use selected layers.
  SAVEBIT_16BITCHANNELS	Use 16 bit channels.
  SAVEBIT_32BITCHANNELS	Use 32 bit channels.
  SAVEBIT_SAVERENDERRESULT	Private.

Return type:

bool

Returns:

Success of writing the bitmap.

HyperFile.WriteContainer(v)

Write the settings in a BaseContainer to the hyperfile.

Parameter:v (BaseContainer) – The container to write to the hyperfile. Return type:bool Returns:Success of writing the value.

HyperFile.WriteLLong(v)

Write a long value to the hyperfile.

Parameter:v (long) – The long to write to the hyperfile. Return type:bool Returns:Success of writing the value.

HyperFile.WriteData(v)

Write data to the container.

Note

This method supports all types GeData in the C++ SDK takes.

Parameter:v (any) – The data. Return type:bool Returns:Success of writing the value.

HyperFile.ReadChar()

Read a character from the hyperfile.

Return type:int Returns:The character or None if reading failed.

HyperFile.ReadUChar()

Read an unsigned character from the hyperfile.

Return type:int Returns:The unsigned character or None if reading failed.

HyperFile.ReadWord()

Read an unsigned word from the hyperfile.

Return type:int Returns:The unsigned word or None if reading failed.

HyperFile.ReadUWord()

Read an unsigned word from the hyperfile.

Return type:int Returns:The unsigned word or None if reading failed.

HyperFile.ReadInt()

Read an int from the hyperfile.

Return type:int Returns:The int or None if reading failed.

HyperFile.ReadULong()

Read an unsigned int from the hyperfile.

Return type:int Returns:The unsigned int or None if reading failed.

HyperFile.ReadFloat()

Read a float from the hyperfile.

Return type:int Returns:The float or None if reading failed.

HyperFile.ReadBool()

Read a bool from the hyperfile.

Return type:int Returns:The bool or None if reading failed.

HyperFile.ReadTime()

Read a BaseTime from the hyperfile.

Return type:int Returns:The BaseTime or None if reading failed.

HyperFile.ReadTime()

Read a BaseTime from the hyperfile.

Return type:int Returns:The BaseTime or None if reading failed.

HyperFile.ReadVector()

Read a Vector from the hyperfile.

Return type:int Returns:The Vector or None if reading failed.

HyperFile.ReadMatrix()

Read a Matrix from the hyperfile.

Return type:int Returns:The Matrix or None if reading failed.

HyperFile.ReadString()

Read a string from the hyperfile.

Return type:int Returns:The string or None if reading failed.

HyperFile.ReadFilename()

Read a path from the hyperfile.

Return type:int Returns:The path or None if reading failed.

HyperFile.ReadImage()

Read a bitmap from the hyperfile.

Return type:BaseBitmap Returns:The bitmap or None if reading failed.

HyperFile.ReadContainer()

Read a container from the hyperfile.

Return type:BaseBitmap Returns:The container or None if reading failed.

HyperFile.ReadLLong()

Read a long from the hyperfile.

Return type:long Returns:The value or None if reading failed.

HyperFile.ReadData()

Read a data from the hyperfile.

Note

This method may return one of the types GeData in the C++ SDK supports.

Return type:any Returns:The value or None if reading failed.

HyperFile.GetError()

Get the error from the last hyperfile operation.

Return type:int Returns:The error number.

HyperFile.SetError(err)

Set the error value for this hyperfile.

Parameter:err (int) – The error number.

HyperFile.ReadValueHeader()

Read the value header from the file. This is only necessary in combination with loops.

Example:

from c4d import storage as st

def ReadSettings(op, hf, level):

    while hf.ReadValueHeader()==st.HFILE_START:
        chunk = hf.ReadChunkStart()
        if not chunk:
            return False

        id = chunk["id"]
        if id==2:
            i1 = hf.ReadInt()
            i2 = hf.ReadInt()
            #do_here
        elif id==3:
            i1 = hf.ReadInt()
            i2 = hf.ReadInt()
            i3 = hf.ReadInt()
            #do_here

        hf.SkipToEndChunk() #never forget this at the end
        if id==0:
            break

    test = hf.ReadString()
    #do here
    return True

Set the error value for this hyperfile.

Rtype h:

int

Returns:

The values are:

HFILE_START	Marks the start of a chunk.
HFILE_STOP	Marks the end of a chunk.
HFILE_CSTOP	Marks the end of a container. (Internal)
HFILE_CHAR	char
HFILE_UCHAR	usigned char
HFILE_WORD	word
HFILE_UWORD	unsigned word
HFILE_INT	int
HFILE_LLONG	long
HFILE_FLOAT	float
HFILE_BOOL	bool
HFILE_TIME	BaseTime
HFILE_VECTOR	Vector
HFILE_MATRIX	Matrix

HFILE_LREAL	internal.
HFILE_LVECTOR	internal.
HFILE_LMATRIX	internal.
HFILE_LULONG	internal.
HFILE_ULONG	internal.

HyperFile.SkipValue(h)

Skip a given type of value.

Parameter:h (int) – The header type to skip.

HyperFile.WriteChunkStart(id, level)

Write a chunk marker into the file indicating the begining of a new chunk of data.

Note

Chunks should only be used if absolutely necessary. If a plugin uses chunks badly then the file structure can become corrupted.

Parameters:

• id (int) – The ID for the chunk.
• level (int) – If you want to write additional information you can increase the level this allows you to easily save/read new values.

Return type:

bool

Returns:

Success of writing the chunk identification.

HyperFile.WriteChunkEnd()

Write a chunk ending marker into the file.

Return type:bool Returns:Success of writing the chunk end.

HyperFile.ReadChunkStart()

Read a chunks identification from the file:

chunk = hf.ReadChunkStart()
if not chunk:
    return

id = chunk["id"] # Chunk ID, int
level = chunk["level"] # Chunk Level, int

Return type:dict Returns:The identification or None on failure.

HyperFile.ReadChunkEnd()

Read a chunks end marker from the file.

Return type:bool Returns:Success of reading the chunk end.

HyperFile.SkipToEndChunk()

Move the file pointer to the end of the chunk.

Note

This should always be called after finishing reading your values from this chunk.

Return type:bool Returns:Success of finding the end of the chunk.

HyperFile.GetDocument()

Gets the active document for the hyper file operation. Can be None, for example when saving layouts.

Return type:BaseDocument Returns:The document.

HyperFile.GetFileVersion()

Get the version of CINEMA 4D that wrote the file. (Only valid during reading a CINEMA 4D scene, object, material etc.)

Return type:int Returns:The file version.

HyperFile.Open(filename, mode, ident)

Opens the hyper file.

Parameters:

• filename (str) – The file to open.
• mode (int) –

  The mode:

  GE_READ	Open the file for reading.
  GE_WRITE	Create a new file for writing. If the file name points to an existing file, it will be overwritten!
  GE_APPEND	Open an existing file for writing and set the position to the end of that file.
  GE_READWRITE	Open the file for both reading and writing.

• ident (int) – File identification.

HyperFile.Open(filename, mode, ident)

Closes the hyper file.