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

Reference