c4d.storage.HyperFile

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 showing how to use the HyperFile class:

import c4d, os
from c4d import storage as st, gui

YOUR_IDENT = 49545 # Choose a custom ident
path = os.path.join("/Users", "Dev", "Desktop", "test.file")
print path
def Write(path, key):
  #write
  print path
  hf = st.HyperFile()
  if hf.Open(ident=key, filename=path, mode=c4d.FILEOPEN_WRITE, error_dialog=c4d.FILEDIALOG_NONE):
    bc = c4d.BaseContainer()
    bc[0] = "test"
    bc[1] = "3"
    hf.WriteContainer(bc)
    hf.Close()
  else:
    gui.MessageDialog("Cannot open file to write.")

def Read(path, key):
  #read
  hf = st.HyperFile()
  if hf.Open(ident=key, filename=path, mode=c4d.FILEOPEN_READ, error_dialog=c4d.FILEDIALOG_NONE):
    bc = hf.ReadContainer()
    hf.Close()
    print bc[0], bc[1] #output: test 3
  else:
    gui.MessageDialog("Cannot open file to read.")

Write(path, YOUR_IDENT)
Read(path, YOUR_IDENT)

Definition

class c4d.storage.HyperFile

Members

HyperFile.__init__()

Allocates a hyper file.

Return type:c4d.storage.HyperFile
Returns:The hyper file.
HyperFile.Open(ident, filename, mode, error_dialog)

Opens the hyper file.

Parameters:
  • ident (int) – File identification.
  • filename (Union[str, c4d.storage.MemoryFileStruct]) – File to open.
  • mode (int) –

    File mode:

    FILEOPEN_APPEND Open an existing file for writing and set the position to the end of that file.
    FILEOPEN_READ Open the file for reading.
    FILEOPEN_WRITE Create a new file for writing. Warning: If the file name points to an existing file, it will be overwritten.
    FILEOPEN_READWRITE Open the file for both reading and writing.
    FILEOPEN_READ_NOCACHE Private.
    FILEOPEN_SHAREDREAD Private.
    FILEOPEN_SHAREDWRITE Private.
  • error_dialog (int) –

    File error dialog:

    FILEDIALOG_NONE Never show an error dialog.
    FILEDIALOG_ANY Show an error dialog for any error.
    FILEDIALOG_IGNOREOPEN Do not show an error dialog if the file does not exist, otherwise like FILEDIALOG_ANY.
Return type:

bool

Returns:

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

HyperFile.Close()

Closes the hyper file.

Return type:bool
Returns:True on success.
HyperFile.WriteChar(v)

Write a character to the hyperfile.

Parameters: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.

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

New in version R15.037.

Write a signed short int to the hyperfile.

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

New in version R15.037.

Write an unsigned short int to the hyperfile.

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

New in version R15.037.

Write an int to the hyperfile.

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

New in version R15.037.

Write an unsigned int to the hyperfile.

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

New in version R15.037.

Write a double precision int value to the hyperfile.

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

New in version R15.037.

Write a double precision unsigned int value to the hyperfile.

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

New in version R16.021.

Write a float value to the hyperfile.

Parameters:v (float) – The value to write to the hyperfile.
Return type:bool
Returns:Success of writing the value.
HyperFile.WriteFloat64(v)

New in version R15.037.

Write a double precision float value to the hyperfile.

Parameters:v (float) – 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.

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

New in version R16.021.

Write a Vector to the hyperfile.

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

New in version R15.037.

Write a double precision Vector to the hyperfile.

Parameters:v (c4d.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.

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

New in version R16.021.

Write a Matrix to the hyperfile.

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

New in version R15.037.

Write a double precision Matrix to the hyperfile.

Parameters:v (c4d.Matrix) – 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.

Parameters: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.

Parameters:v (c4d.BaseTime) – 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.

Parameters: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.

Parameters:v (str) – The path to write to the hyperfile.
Return type:bool
Returns:Success of writing the value.
HyperFile.WriteImage(v, format, data, savebits=c4d.SAVEBIT_ALPHA)

Write an image to the hyperfile.

Parameters:
  • v (c4d.bitmaps.BaseBitmap) – The bitmap to write to the hyperfile.
  • format (int) –

    The image format:

    FILTER_TIF TIFF.
    FILTER_TGA TGA.
    FILTER_BMP BMP.
    FILTER_IFF IFF.
    FILTER_JPG JPEG.
    FILTER_PICT PICT.
    FILTER_PSD PSD.
    FILTER_RLA RLA.
    FILTER_RPF RPF.
    FILTER_B3D BodyPaint 3D.
    FILTER_TIF_B3D TIFF BodyPaint 3D.
    FILTER_PSB PSB.
    FILTER_AVI AVI Movie.
    FILTER_MOVIE Quicktime Movie.
    FILTER_QTVRSAVER_PANORAMA QTVR Panorama.
    FILTER_QTVRSAVER_OBJECT QTVR Object.
    FILTER_HDR HDR.
    FILTER_EXR_LOAD EXR (Load).
    FILTER_EXR EXR.
    FILTER_PNG PNG.
    FILTER_IES IES.
    FILTER_B3DNET BodyPaint 3D NET. Private.
    FILTER_DPX DPX.
    FILTER_DDS

    New in version R19.

    DDS.

  • data (c4d.BaseContainer) –

    A container with additional format settings, or None.

    SAVEBIT_NONE None.
    SAVEBIT_ALPHA Save the alpha channel(s) in the file. (For filter plugins, do not save an alpha channel if this is not set.)
    SAVEBIT_MULTILAYER Save multiple layers.
    SAVEBIT_USESELECTEDLAYERS Use selected layers.
    SAVEBIT_16BITCHANNELS Use 16-bit channels.
    SAVEBIT_GREYSCALE Save in grayscale mode.
    SAVEBIT_INTERNALNET Private.
    SAVEBIT_DONTMERGE Avoid merging of layers in BodyPaint 3D files.
    SAVEBIT_32BITCHANNELS Use 32-bit channels.
    SAVEBIT_SAVERENDERRESULT Private.
    SAVEBIT_FIRSTALPHA_ONLY Private.
  • savebits (int) –

    The save bits:

    SAVEBIT_NONE None.
    SAVEBIT_ALPHA Save the alpha channel(s) in the file. (For filter plugins, do not save an alpha channel if this is not set.)
    SAVEBIT_MULTILAYER Save multiple layers.
    SAVEBIT_USESELECTEDLAYERS Use selected layers.
    SAVEBIT_16BITCHANNELS Use 16-bit channels.
    SAVEBIT_GREYSCALE Save in grayscale mode.
    SAVEBIT_INTERNALNET Private.
    SAVEBIT_DONTMERGE Avoid merging of layers in BodyPaint 3D files.
    SAVEBIT_32BITCHANNELS Use 32-bit channels.
    SAVEBIT_SAVERENDERRESULT Private.
    SAVEBIT_FIRSTALPHA_ONLY Private.
Return type:

bool

Returns:

Success of writing the image.

HyperFile.WriteContainer(v)

Write the settings in a BaseContainer to the hyperfile.

Parameters:v (c4d.BaseContainer) – The container to write to the hyperfile.
Return type:bool
Returns:Success of writing the value.
HyperFile.WriteMemory(data)

Write a block of memory to the hyperfile.

Note

Only use this when you need to, be aware that the byte sequences will not be platform independent.

Parameters:data (c4d.storage.ByteSeq) – The data to write to the hyperfile.
Return type:bool
Returns:Success of writing the data.
HyperFile.WriteData(v)

Write data to the container.

Note

Please check the constructor of GeData in the C++ SDK to see what type this method accepts.

Parameters: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.ReadInt16()

New in version R15.037.

Read a signed word from the hyperfile.

Return type:int
Returns:The unsigned word or None if reading failed.
HyperFile.ReadUInt16()

New in version R15.037.

Read an unsigned word from the hyperfile.

Return type:int
Returns:The unsigned word or None if reading failed.
HyperFile.ReadInt32()

New in version R15.037.

Read an int from the hyperfile.

Return type:int
Returns:The unsigned int or None if reading failed.
HyperFile.ReadUInt32()

New in version R15.037.

Read an unsigned int from the hyperfile.

Return type:int
Returns:The unsigned int or None if reading failed.
HyperFile.ReadInt64()

New in version R15.037.

Read a double precision int from the hyperfile.

Return type:int
Returns:The value or None if reading failed.
HyperFile.ReadUInt64()

New in version R16.021.

Read a double precision unsigned int from the hyperfile.

Return type:int
Returns:The value or None if reading failed.
HyperFile.ReadFloat()

New in version R15.037.

Read a float from the hyperfile.

Return type:float
Returns:The float or None if reading failed.
HyperFile.ReadFloat32()

New in version R16.021.

Read a float from the hyperfile.

Return type:float
Returns:The float or None if reading failed.
HyperFile.ReadFloat64()

New in version R15.037.

Read a double precision float from the hyperfile.

Return type:float
Returns:The float or None if reading failed.
HyperFile.ReadVector()

Read a Vector from the hyperfile.

Return type:c4d.Vector
Returns:The vector or None if reading failed.
HyperFile.ReadVector32()

New in version R16.021.

Read a Vector from the hyperfile.

Return type:c4d.Vector
Returns:The vector or None if reading failed.
HyperFile.ReadVector64()

New in version R15.037.

Read a double precision Vector from the hyperfile.

Return type:c4d.Vector
Returns:The vector or None if reading failed.
HyperFile.ReadMatrix()

Read a Matrix from the hyperfile.

Return type:c4d.Matrix
Returns:The matrix or None if reading failed.
HyperFile.ReadMatrix32()

New in version R16.021.

Read a Matrix from the hyperfile.

Return type:c4d.Matrix
Returns:The matrix or None if reading failed.
HyperFile.ReadMatrix64()

New in version R15.037.

Read a double precision Matrix from the hyperfile.

Return type:c4d.Matrix
Returns:The matrix or None if reading failed.
HyperFile.ReadBool()

Read a bool from the hyperfile.

Return type:bool
Returns:The bool or None if reading failed.
HyperFile.ReadTime()

Read a BaseTime from the hyperfile.

Return type:c4d.BaseTime
Returns:The time or None if reading failed.
HyperFile.ReadString()

Read a string from the hyperfile.

Return type:str
Returns:The string or None if reading failed.
HyperFile.ReadFilename()

Read a path from the hyperfile.

Return type:str
Returns:The path or None if reading failed.
HyperFile.ReadImage()

Read a bitmap from the hyperfile.

Return type:c4d.bitmaps.BaseBitmap
Returns:The bitmap or None if reading failed.
HyperFile.ReadContainer()

Read a container from the hyperfile.

Return type:c4d.bitmaps.BaseBitmap
Returns:The container or None if reading failed.
HyperFile.ReadMemory()

Read a block of memory from the hyperfile.

Note

Only use this when you need to, be aware that the byte sequences will not be platform independent.

Return type:c4d.storage.ByteSeq
Returns:The value or None if reading failed.
HyperFile.ReadData()

Read a data from the hyperfile.

Note

Please check the constructor of GeData in the C++ SDK to see what type this method accepts.

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.

Parameters: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.HYPERFILEVALUE_START:
    chunk = hf.ReadChunkStart()
    if not chunk:
      return False

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

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

  test = hf.ReadString()
  #do here
  return True
Return type:int
Returns:The header value or None:
HYPERFILEVALUE_NONE None.
HYPERFILEVALUE_START Marks the start of a chunk.
HYPERFILEVALUE_STOP Marks the end of a chunk.
HYPERFILEVALUE_CSTOP Marks the end of a container. Internal.
HYPERFILEVALUE_CHAR Integer.
HYPERFILEVALUE_UCHAR Integer.
HYPERFILEVALUE_INT16 Integer.
HYPERFILEVALUE_UINT16 Integer.
HYPERFILEVALUE_INT32 Integer.
HYPERFILEVALUE_UINT32 Integer.
HYPERFILEVALUE_INT64 Integer.
HYPERFILEVALUE_UINT64 Integer.
HYPERFILEVALUE_FLOAT Float.
HYPERFILEVALUE_FLOAT32 Float.
HYPERFILEVALUE_FLOAT64 Float.
HYPERFILEVALUE_TIME BaseTime.
HYPERFILEVALUE_VECTOR Vector.
HYPERFILEVALUE_VECTOR32 Vector.
HYPERFILEVALUE_VECTOR64 Vector.
HYPERFILEVALUE_MATRIX Matrix.
HYPERFILEVALUE_MATRIX32 Matrix.
HYPERFILEVALUE_MATRIX64 Matrix.
HYPERFILEVALUE_MEMORY Memory.
HYPERFILEVALUE_IMAGE Image.
HYPERFILEVALUE_STRING String.
HYPERFILEVALUE_FILENAME String.
HYPERFILEVALUE_CONTAINER BaseContainer.
HYPERFILEVALUE_ALIASLINK BaseList2D.
HyperFile.SkipValue(h)

Skip a given type of value.

Parameters:h (int) –

The hyper file value to skip:

HYPERFILEVALUE_NONE None.
HYPERFILEVALUE_START Marks the start of a chunk.
HYPERFILEVALUE_STOP Marks the end of a chunk.
HYPERFILEVALUE_CSTOP Marks the end of a container. Internal.
HYPERFILEVALUE_CHAR Integer.
HYPERFILEVALUE_UCHAR Integer.
HYPERFILEVALUE_INT16 Integer.
HYPERFILEVALUE_UINT16 Integer.
HYPERFILEVALUE_INT32 Integer.
HYPERFILEVALUE_UINT32 Integer.
HYPERFILEVALUE_INT64 Integer.
HYPERFILEVALUE_UINT64 Integer.
HYPERFILEVALUE_FLOAT Float.
HYPERFILEVALUE_FLOAT32 Float.
HYPERFILEVALUE_FLOAT64 Float.
HYPERFILEVALUE_TIME BaseTime.
HYPERFILEVALUE_VECTOR Vector.
HYPERFILEVALUE_VECTOR32 Vector.
HYPERFILEVALUE_VECTOR64 Vector.
HYPERFILEVALUE_MATRIX Matrix.
HYPERFILEVALUE_MATRIX32 Matrix.
HYPERFILEVALUE_MATRIX64 Matrix.
HYPERFILEVALUE_MEMORY Memory.
HYPERFILEVALUE_IMAGE Image.
HYPERFILEVALUE_STRING String.
HYPERFILEVALUE_FILENAME String.
HYPERFILEVALUE_CONTAINER BaseContainer.
HYPERFILEVALUE_ALIASLINK BaseList2D.
rtype:bool
return:True if the value was of the given header type and it was skipped, otherwise False.
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 chunk==None: return

id = chunk["id"] # Chunk ID, int
level = chunk["level"] # Chunk Level, int
Return type:dict{id: int, level: int}
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:c4d.documents.BaseDocument
Returns:The document or None.
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.