com.openinventor.inventor

Class SoInput

java.lang.Object

com.openinventor.inventor.Inventor

com.openinventor.inventor.SoInput

public class SoInput
extends Inventor

Used to read Open Inventor data files. This class is used by the SoDB reading routines when reading Open Inventor (.iv) format data or various geometry data formats that can be converted into an Open Inventor scene graph. The input source can be the standard input stream (default), a file (see openFile) or a buffer in memory (see setBuffer). SoInput can search for a file in a list of directories (see addDirectoryFirst etc). SoInput can report progress during the input operation (see updateReadPercent).

SoInput is typically used with SoDB.read or SoDB.readAll to load data and create a scene graph. There is an example code fragment on the SoDB page.

NOTE: Applications should always check the result of calling the openFile() method. If the call fails, the SoInput object itself is still valid and remains in the default state. Calling SoDB.readAll(), or methods like getHeader() and isValidFile(), with a default SoInput object will make the application appear to "hang" because it is waiting for data on standard input. To check if a file exists, get file properties, etc see SbFileHelper.

File formats

SoInput supports ASCII (default) and binary Open Inventor formats. Since Open Inventor 8.1, both the ASCII and binary formats can be compressed using the gz format (e.g. using gzip). The file extension 'ivz' is recognized for compressed Open Inventor files, but is not mandatory. In fact the initial bytes of the file are checked when the file is opened to automatically determine if it is compressed or not. This feature uses the module IvDLZlib.

SoInput also has built-in support for:

• VRML97 format (.wrl)
• X3D Classic VRML format (.x3dv) See VRML_LIMITATIONS for details.

Additional input readers are provided as plugins for:

• OpenFlight format (.flt)
• DXF format (.dxf)
• STL format (.stl)

<font color="#0000FF">NOTE:</font> OpenFlight format is not supported in Open Inventor 10.0 and later.

These formats require redistributing the corresponding plugin library with the application.

• OpenFlight : fei.inventor.io.flt (e.g. fei.inventor.io.flt.dll on Windows).
• DXF : fei.inventor.io.dxf (e.g. fei.inventor.io.dxf.dll on Windows).
• STL : fei.inventor.io.stl (e.g. fei.inventor.io.stl.dll on Windows).

Open Inventor also supports many standard CAD file formats. See SoCADInputReader for the current list. These formats also require redistributing the corresponding plugin library (fei.inventor.io.cad) with the application.

SoInput can also be extended with custom file format readers. Input readers are defined as new classes inheriting from the SoInputReader class.. See SoInputReader class for more information about defining and loading new readers

For Open Inventor format files, users can also register additional valid file headers. When reading, SoInput skips over Open Inventor comments (from '#' to end of line) and can stack input files. When EOF is reached, the stack is popped.

Directory List

SoInput maintains a list of directories (initially empty). Generally Open Inventor classes that need to open a named file will search for the file in each of these directories in order. This includes SoInput (the openFile() method), SoTexture2, SoFragmentShader and other nodes that have a "filename" field.

Note: SoInput is not currently used for loading volume data files in VolumeViz. SoDataSet and its subclasses (SoVolumeData etc) do not search the list of directories maintained by SoInput when attempting to open a file. However the directory list is searched to find volume shader files (SoVolumeShader, SoVolumeRenderingQuality, etc).

The SoInput directory list is initialized from the environnment variable OIV_FILE_SEARCH_PATHS. This variable may be set to a semi-colon separated list of directory paths. The specified paths may use variables in $name format, e.g. "$OIVHOME", which will be replaced by the value returned by SoPreferences for that name. Additional directories may be added to the directory list using the static methods addDirectoryLast etc.

Static utility method findAbsolutePath() returns the full path of a file if it can be found in one of the directories in the list.

OpenFlight Input Limitations:

The supported OpenFlight file format release is 15.7. Releases 14.2 up to 15.7 may or may not be converted successfully. Newer OpenFlight opcodes (15.8 or later) may not be converted successfully.

Some opcodes are not converted (or partially converted):

• Because their conversion is not implemented yet.
  32 (COLOR PALETTE), 83 (EYEPOINT TRACKPLANE), 89 (MORPH VERTEX LIST), 113 (MATERIAL PALETTE), 115 (CAT), 116 (CAT DATA), 122 (PUSH ATTRIBUTE), 123 (POP ATTRIBUTE), 125 (ADAPTIVE ATTRIBUTE), 126 (CURVE NODE).
• Because they are not commonly used.
  50 (VECTOR), 51 (OLD BOUNDING BOX), 52 (MULTI TEXTURE), 53 (UV VERTEX LIST (MULTI TEXTURE)), 84 (MESH), 85 (LOCAL VERTEX POOL), 86 (MESH PRIMITIVE), 87 (ROAD SEGMENT), 88 (ROAD ZONE), 90 (BEHAVIOR PALETTE), 91 (SOUND), 92 (ROAD PATH), 93 (SOUND PALETTE), 95 (TEXT), 97 (LINE STYLE), 101 (LIGHT SOURCE), 102 (LIGHT SOURCE PALETTE), 110 (HISTOGRAM BOUNDING VOLUME), 111 (LIGHT POINT), 112 (TEXTURE MAPPING PALETTE), 113 (MATERIAL PALETTE), 115 (CAT), 116 (CAT DATA), 122 (PUSH ATTRIBUTE), 123 (POP ATTRIBUTE), 125 (ADAPTIVE ATTRIBUTE), 126 (CURVE NODE).
• Because they are obsolete.
  6 (VERTEX WITH ID), 12 (TRANSLATE), 13 (DOF), 16 (INSTANCE REFERENCE), 17 (INSTANCE DEFINITION), 23 (CONTINUATION), 40 (TRANSLATE), 41 (ROTATE ABOUT POINT), 42 (ROTATE ABOUT EDGE), 43 (SCALE), 44 (OLD TRANSLATE), 46 (OLD ROTATE ABOUT POINT), 47 (ROTATE AND/OR SCALE TO POINT), 48 (PUT TRANSFORM), 65 (EYEPOINT PALETTE), 77 (SCALE).
• Because they are not defined in OpenFlight file format release 15.7.
  100 (EXTENSION), reserved entities.

It is anticipated that these lists will be shorter in future releases.

Here is the list of information that may actually be ignored: latitude and longitude, projection type, earth model, UTM zone, group animation flags, object flags and relative priority, face draw type and light mode, degree of freedom min and max (only keep current position), 0% morph vertex indices, external reference flags, several vertex flag bits and normals, name table, texture mapping palette, texture attribute files, road path and zone files, and linkage parameter IDs.

DXF Input Limitations:

The supported DXF file format release is 14.

The limitations are:

• CLASSES, OBJECTS and THUMBNAILIMAGE sections are ignored.
• TABLES section: APPID, BLOCK_RECORD,DIMSTYLE, LSTYLE, UCS, VIEW, VIEWPORT are ignored.
• ENTITIES section: 3DSOLID, ARCALIGNEDTEXT, ATTDEF, BODY, DIMENSION, HATCH, IMAGE, LEADER, OLEFRAME, OLEFRAME2, REGION, RTEXT, SHAPE, TOLERANCE, TRACE, VIEWPORT, WIPEOUT are ignored.

VRML Input Limitations:

Not all nodes are supported when reading VRML files. Here is list of supported nodes:

GeoVRML nodes:

• SoVRMLGeoLOD
• SoVRMLGeoElevationGrid
• SoVRMLGeoOrigin
• SoVRMLGeoLocation
• SoVRMLGeoCoordinate

Special Group nodes:

• SoVRMLInline
• SoVRMLLOD
• SoVRMLSwitch

Common nodes:

• SoVRMLDirectionalLight
• SoVRMLPointLight
• SoVRMLSpotLight
• SoVRMLWorldInfo

Geometry nodes:

• SoVRMLElevationGrid
• SoVRMLExtrusion
• SoVRMLIndexedFaceSet
• SoVRMLIndexedLineSet
• SoVRMLPointSet
• SoVRMLBox
• SoVRMLCone
• SoVRMLCylinder
• SoVRMLSphere
• SoVRMLText
• SoVRMLShape

Geometry properties:

• SoVRMLCoordinate
• SoVRMLColor
• SoVRMLTextureCoordinate
• SoVRMLNormal

Geometry appearance:

• SoVRMLMaterial
• SoVRMLImageTexture
• SoVRMLPixelTexture
• SoVRMLTextureTransform
• SoVRMLFontStyle
• SoVRMLAppearance

Group nodes:

• SoVRMLTransform
• SoVRMLAnchor
• SoVRMLBillboard
• SoVRMLCollision
• SoVRMLParent
• SoVRMLGroup
• SoVRMLStaticGroup

Special nodes:

• SoVRMLPROTOInstance

See also:

SoDB, SoOutput, SoTranReceiver, SoInputParameters, SoInputReader, SoCADInputReaderParameters

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SoInput.FileTypes Deprecated.

Nested classes/interfaces inherited from class com.openinventor.inventor.Inventor

Inventor.ConstructorCommand

Field Summary

Fields

Modifier and Type	Field and Description
static int	ALL Deprecated. Use SoInput.FileTypes.ALL instead.
static int	CATIA5 Deprecated. Use SoInput.FileTypes.CATIA5 instead.
static java.lang.String	DIRECTORIES_SEPARATOR
static int	DXF Deprecated. Use SoInput.FileTypes.DXF instead.
static int	IGES Deprecated. Use SoInput.FileTypes.IGES instead.
static int	OpenFlight Deprecated. Use SoInput.FileTypes.OpenFlight instead.
static int	OpenInventor Deprecated. Use SoInput.FileTypes.OpenInventor instead.
static int	STEP Deprecated. Use SoInput.FileTypes.STEP instead.

Fields inherited from class com.openinventor.inventor.Inventor

VERBOSE_LEVEL, ZeroHandle

Constructor Summary

Constructors

Constructor and Description
SoInput() Constructor.

Method Summary

Modifier and Type	Method and Description
static void	addDirectoryFirst(java.lang.String dirName) The SoInput class maintains a global list of directories that is searched to find files when opening them.
static void	addDirectoryLast(java.lang.String dirName) The SoInput class maintains a global list of directories that is searched to find files when opening them.
static void	addEnvDirectoriesFirst(java.lang.String envVarName) Calls addEnvDirectoriesFirst(envVarName, DIRECTORIES_SEPARATOR).
static void	addEnvDirectoriesFirst(java.lang.String envVarName, java.lang.String dirSep) The SoInput class maintains a global list of directories that is searched to find files when opening them.
static void	addEnvDirectoriesLast(java.lang.String envVarName) Calls addEnvDirectoriesLast(envVarName, DIRECTORIES_SEPARATOR).
static void	addEnvDirectoriesLast(java.lang.String envVarName, java.lang.String dirSep) The SoInput class maintains a global list of directories that is searched to find files when opening them.
static void	clearDirectories() Clears the list of directories (including the current directory).
void	closeFile() Closes all files on stack opened with openFile() or pushFile().
static java.lang.String	findAbsolutePath(java.lang.String fileName) Returns absolute path of given file by looking in SoInput standard directories.
java.lang.String	getCurFileName() Returns full name (including directory path) of current file.
SoInput.FileTypes	getCurFileType() Deprecated. As of Open Inventor 9100 See documentation for more details
java.lang.String	getCurStringFileName() Returns full name (including directory path) of current file.
java.lang.String	getHeader() Returns the header of the file being read.
SoInputParameters	getInputParameters() Return the current SoInputParameters.
float	getIVVersion() Returns the Open Inventor file version of the file being read (2.1).
int	getNumBytesRead() Returns the number of bytes read.
boolean	isValidBuffer() Returns true if the current buffer is valid.
boolean	isValidFile() Returns true if the currently open file is a valid Open Inventor file.
boolean	openFile(java.lang.String fileName) Calls openFile(fileName, false, false).
boolean	openFile(java.lang.String fileName, boolean okIfNotFound) Calls openFile(fileName, okIfNotFound, false).
boolean	openFile(java.lang.String fileName, boolean okIfNotFound, boolean aSync) Opens named file.
boolean	openURL(java.net.URL fileURL) Using a java URL, open an IV file.
boolean	pushFile(java.lang.String fileName) Opens named file.
static void	removeDirectory(java.lang.String dirName) Removes named directory from the list.
void	setBuffer(byte[] buffer) Set up buffer to read from.
void	setBuffer(byte[] buffer, int size) Set up buffer to read from.
void	setBuffer(java.lang.String buffer, int size) Set up buffer to read from.
void	setCurFileType(SoInput.FileTypes fileType) Deprecated. As of Open Inventor 9100 See documentation for more details
void	setInputParameters(SoInputParameters parameters) Specify parameters to modify/control actions during the read of a file.
void	updateReadPercent(double readPercentage) Reports the percentage of bytes read from the file.

Methods inherited from class com.openinventor.inventor.Inventor

dispose, getAddress, getNativeResourceHandle, startInternalThreads, stopInternalThreads

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DIRECTORIES_SEPARATOR

public static final java.lang.String DIRECTORIES_SEPARATOR

OpenInventor

@Deprecated
public static final int OpenInventor

Deprecated. Use SoInput.FileTypes.OpenInventor instead.

OpenFlight

@Deprecated
public static final int OpenFlight

Deprecated. Use SoInput.FileTypes.OpenFlight instead.

DXF

@Deprecated
public static final int DXF

Deprecated. Use SoInput.FileTypes.DXF instead.

IGES

@Deprecated
public static final int IGES

Deprecated. Use SoInput.FileTypes.IGES instead.

STEP

@Deprecated
public static final int STEP

Deprecated. Use SoInput.FileTypes.STEP instead.

CATIA5

@Deprecated
public static final int CATIA5

Deprecated. Use SoInput.FileTypes.CATIA5 instead.

ALL

@Deprecated
public static final int ALL

Deprecated. Use SoInput.FileTypes.ALL instead.

Constructor Detail

SoInput

public SoInput()

Constructor. The default SoInput reads from stdin.

Method Detail

setBuffer

public void setBuffer(byte[] buffer)

Set up buffer to read from.

Parameters:

buffer - contains the binary iv representation

setBuffer

public void setBuffer(byte[] buffer,
                      int size)

Set up buffer to read from.

Parameters:

buffer - contains the binary iv representation

size - indicates how many bytes should be read from buffer

setBuffer

public void setBuffer(java.lang.String buffer,
                      int size)

Set up buffer to read from.

Parameters:

buffer - contains the iv representation in a string.

size - indicates how many characters should be read from buffer

openURL

public boolean openURL(java.net.URL fileURL)

Using a java URL, open an IV file. If the URL indicates an address through the net, be sure that your machine is connected.

Returns:

false if the URL is not correct or if it could not be opened ; true if the resulting buffer is valid.

openFile

public boolean openFile(java.lang.String fileName)

Calls openFile(fileName, false, false).

openFile

public boolean openFile(java.lang.String fileName,
                        boolean okIfNotFound)

Calls openFile(fileName, okIfNotFound, false).

addEnvDirectoriesLast

public static void addEnvDirectoriesLast(java.lang.String envVarName)

Calls addEnvDirectoriesLast(envVarName, DIRECTORIES_SEPARATOR).

addEnvDirectoriesFirst

public static void addEnvDirectoriesFirst(java.lang.String envVarName)

Calls addEnvDirectoriesFirst(envVarName, DIRECTORIES_SEPARATOR).

closeFile

public void closeFile()

Closes all files on stack opened with openFile() or pushFile().

isValidFile

public boolean isValidFile()

Returns true if the currently open file is a valid Open Inventor file. File must begin with a standard Open Inventor header or one that has been registered with SoDB.registerHeader(). Note that by default (when no file or buffer is open), SoInput reads from standard input, which may make the application appear to "hang".

setCurFileType

@Deprecated
public void setCurFileType(SoInput.FileTypes fileType)

Deprecated. As of Open Inventor 9100 See documentation for more details

Sets the type of the current file. Deprecated since Open Inventor 9100
No longer used.

isValidBuffer

public boolean isValidBuffer()

Returns true if the current buffer is valid. Buffer must begin with a standard Open Inventor header or one that has been registered with SoDB.registerHeader(). Note that by default (when no file or buffer is open), SoInput reads from standard input, which may make the application appear to "hang".

openFile

public boolean openFile(java.lang.String fileName,
                        boolean okIfNotFound,
                        boolean aSync)

Opens named file. Returns false on error. If okIfNotFound is false (the default), prints an error message if the file could not be found. If aSync is true (false by default) the file is read asynchronously (the reading starts immediately although it isn't fully buffered).

The file name may contain variables in $name format, e.g. "$OIVHOME", which will be replaced by the value returned by SoPreferences for that name.

pushFile

public boolean pushFile(java.lang.String fileName)

Opens named file. Returns false on error. When EOF is reached, the stack is popped.

The file name may contain variables in $name format, e.g. "$OIVHOME", which will be replaced by the value returned by SoPreferences for that name.

addEnvDirectoriesFirst

public static void addEnvDirectoriesFirst(java.lang.String envVarName,
                                          java.lang.String dirSep)

The SoInput class maintains a global list of directories that is searched to find files when opening them. Directories are searched in order. This routine adds directories named in the value of the given environment variable to the beginning of the list.

NOTE: On Microsoft Windows systems the default dirSep value causes a problem. For example, the string "C:/myDir" will be interpreted as two different directories "C/" and "/myDir".. To avoid this problem explicitly set dirSep to ";" (semicolon).

Parameters:

envVarName - The name of the environment variable.

dirSep - A string containing zero or more directory separator characters.

addEnvDirectoriesLast

public static void addEnvDirectoriesLast(java.lang.String envVarName,
                                         java.lang.String dirSep)

The SoInput class maintains a global list of directories that is searched to find files when opening them. Directories are searched in order. This routine adds directories named in the value of the given environment variable to the end of the list.

NOTE: On Microsoft Windows systems the default dirSep value causes a problem. For example, the string "C:/myDir" will be interpreted as two different directories "C/" and "/myDir".. To avoid this problem explicitly set dirSep to ";" (semicolon).

Parameters:

envVarName - The name of the environment variable.

dirSep - A string containing zero or more directory separator characters.

addDirectoryLast

public static void addDirectoryLast(java.lang.String dirName)

The SoInput class maintains a global list of directories that is searched to find files when opening them. Directories are searched in order. This routine adds a directory to the end of the list.

clearDirectories

public static void clearDirectories()

Clears the list of directories (including the current directory).

findAbsolutePath

public static java.lang.String findAbsolutePath(java.lang.String fileName)

Returns absolute path of given file by looking in SoInput standard directories. Returns true on success.

The file name may contain variables in $name format, e.g. "$OIVHOME", which will be replaced by the value returned by SoPreferences for that name.

removeDirectory

public static void removeDirectory(java.lang.String dirName)

Removes named directory from the list.

addDirectoryFirst

public static void addDirectoryFirst(java.lang.String dirName)

The SoInput class maintains a global list of directories that is searched to find files when opening them. Directories are searched in order. This routine adds a directory to the beginning of the list.

getHeader

public java.lang.String getHeader()

Returns the header of the file being read. Note that by default (when no file or buffer is open), SoInput reads from standard input, which may make the application appear to "hang".

getIVVersion

public float getIVVersion()

Returns the Open Inventor file version of the file being read (2.1). If the file has a header registered through SoDB.registerHeader(), the returned version is the Open Inventor version registered with the header. Returns 0.0 if no file or buffer is open.

getNumBytesRead

public int getNumBytesRead()

Returns the number of bytes read.

getCurFileName

public java.lang.String getCurFileName()

Returns full name (including directory path) of current file. Returns NULL if no file is open or if reading from a buffer.

getCurStringFileName

public java.lang.String getCurStringFileName()

Returns full name (including directory path) of current file. Returns an empty string (isEmpty() will be true) if no file is open or if reading from a buffer.

getCurFileType

@Deprecated
public SoInput.FileTypes getCurFileType()

Deprecated. As of Open Inventor 9100 See documentation for more details

If no type has been specified, the default type is Open Inventor. Returns the type of the current file.Deprecated since Open Inventor 9100
No longer used.

getInputParameters

public SoInputParameters getInputParameters()

Return the current SoInputParameters.

updateReadPercent

public void updateReadPercent(double readPercentage)

Reports the percentage of bytes read from the file.
Derive a new class and override this method if you want to implement a progress bar.

setInputParameters

public void setInputParameters(SoInputParameters parameters)

Specify parameters to modify/control actions during the read of a file. For example, use an instance of SoCADInputReaderParameters for file formats handled by the SoCADFileFormat module (IGES, STEP, CATIA, ...).