Assimp  v4.1. (December 2018)
Usage

Access by C++ class interface

The assimp library can be accessed by both a class or flat function interface. The C++ class interface is the preferred way of interaction: you create an instance of class Assimp::Importer, maybe adjust some settings of it and then call Assimp::Importer::ReadFile(). The class will read the files and process its data, handing back the imported data as a pointer to an aiScene to you. You can now extract the data you need from the file. The importer manages all the resources for itsself. If the importer is destroyed, all the data that was created/read by it will be destroyed, too. So the easiest way to use the Importer is to create an instance locally, use its results and then simply let it go out of scope.

C++ example:

#include <assimp/Importer.hpp> // C++ importer interface
#include <assimp/scene.h> // Output data structure
#include <assimp/postprocess.h> // Post processing flags
bool DoTheImportThing( const std::string& pFile)
{
// Create an instance of the Importer class
// And have it read the given file with some example postprocessing
// Usually - if speed is not the most important aspect for you - you'll
// probably to request more postprocessing than we do in this example.
const aiScene* scene = importer.ReadFile( pFile,
// If the import failed, report it
if( !scene)
{
DoTheErrorLogging( importer.GetErrorString());
return false;
}
// Now we can access the file's contents.
DoTheSceneProcessing( scene);
// We're done. Everything will be cleaned up by the importer destructor
return true;
}

What exactly is read from the files and how you interpret it is described at the Data Structures page. The post processing steps that the assimp library can apply to the imported data are listed at aiPostProcessSteps. See the pp Post processing page for more details.

Note that the aiScene data structure returned is declared 'const'. Yes, you can get rid of these 5 letters with a simple cast. Yes, you may do that. No, it's not recommended (and it's suicide in DLL builds if you try to use new or delete on any of the arrays in the scene).

Access by plain-c function interface

The plain function interface is just as simple, but requires you to manually call the clean-up after you're done with the imported data. To start the import process, call aiImportFile() with the filename in question and the desired postprocessing flags like above. If the call is successful, an aiScene pointer with the imported data is handed back to you. When you're done with the extraction of the data you're interested in, call aiReleaseImport() on the imported scene to clean up all resources associated with the import.

C example:

#include <assimp/cimport.h> // Plain-C interface
#include <assimp/scene.h> // Output data structure
#include <assimp/postprocess.h> // Post processing flags
bool DoTheImportThing( const char* pFile)
{
// Start the import on the given file with some example postprocessing
// Usually - if speed is not the most important aspect for you - you'll t
// probably to request more postprocessing than we do in this example.
const aiScene* scene = aiImportFile( pFile,
// If the import failed, report it
if( !scene)
{
DoTheErrorLogging( aiGetErrorString());
return false;
}
// Now we can access the file's contents
DoTheSceneProcessing( scene);
// We're done. Release all resources associated with this import
return true;
}

Using custom IO logic with the C++ class interface

The assimp library needs to access files internally. This of course applies to the file you want to read, but also to additional files in the same folder for certain file formats. By default, standard C/C++ IO logic is used to access these files. If your application works in a special environment where custom logic is needed to access the specified files, you have to supply custom implementations of IOStream and IOSystem. A shortened example might look like this:

// My own implementation of IOStream
class MyIOStream : public Assimp::IOStream
{
friend class MyIOSystem;
protected:
// Constructor protected for private usage by MyIOSystem
MyIOStream(void);
public:
~MyIOStream(void);
size_t Read( void* pvBuffer, size_t pSize, size_t pCount) { ... }
size_t Write( const void* pvBuffer, size_t pSize, size_t pCount) { ... }
aiReturn Seek( size_t pOffset, aiOrigin pOrigin) { ... }
size_t Tell() const { ... }
size_t FileSize() const { ... }
void Flush () { ... }
};
// Fisher Price - My First Filesystem
class MyIOSystem : public Assimp::IOSystem
{
MyIOSystem() { ... }
~MyIOSystem() { ... }
// Check whether a specific file exists
bool Exists( const std::string& pFile) const {
..
}
// Get the path delimiter character we'd like to see
char GetOsSeparator() const {
return '/';
}
// ... and finally a method to open a custom stream
IOStream* Open( const std::string& pFile, const std::string& pMode) {
return new MyIOStream( ... );
}
void Close( IOStream* pFile) { delete pFile; }
};

Now that your IO system is implemented, supply an instance of it to the Importer object by calling Assimp::Importer::SetIOHandler().

void DoTheImportThing( const std::string& pFile)
{
// put my custom IO handling in place
importer.SetIOHandler( new MyIOSystem());
// the import process will now use this implementation to access any file
importer.ReadFile( pFile, SomeFlag | SomeOtherFlag);
}

Using custom IO logic with the plain-c function interface

The C interface also provides a way to override the file system. Control is not as fine-grained as for C++ although surely enough for almost any purpose. The process is simple:

  • Include cfileio.h
  • Fill an aiFileIO structure with custom file system callbacks (they're self-explanatory as they work similar to the CRT's fXXX functions)
  • .. and pass it as parameter to aiImportFileEx

Logging

The assimp library provides an easy mechanism to log messages. For instance if you want to check the state of your import and you just want to see, after which preprocessing step the import-process was aborted you can take a look into the log. Per default the assimp-library provides a default log implementation, where you can log your user specific message by calling it as a singleton with the requested logging-type. To see how this works take a look to this:

using namespace Assimp;
// Create a logger instance
// Now I am ready for logging my stuff
DefaultLogger::get()->info("this is my info-call");
// Kill it after the work is done

At first you have to create the default-logger-instance (create). Now you are ready to rock and can log a little bit around. After that you should kill it to release the singleton instance.

If you want to integrate the assimp-log into your own GUI it my be helpful to have a mechanism writing the logs into your own log windows. The logger interface provides this by implementing an interface called LogStream. You can attach and detach this log stream to the default-logger instance or any implementation derived from Logger. Just derivate your own logger from the abstract base class LogStream and overwrite the write-method:

// Example stream
class myStream : public LogStream
{
public:
// Write womethink using your own functionality
void write(const char* message)
{
::printf("%s\n", message);
}
};
// Select the kinds of messages you want to receive on this log stream
const unsigned int severity = Logger::Debugging|Logger::Info|Logger::Err|Logger::Warn;
// Attaching it to the default logger
Assimp::DefaultLogger::get()->attachStream( new myStream, severity );

The severity level controls the kind of message which will be written into the attached stream. If you just want to log errors and warnings set the warn and error severity flag for those severities. It is also possible to remove a self defined logstream from an error severity by detaching it with the severity flag set:

unsigned int severity = 0;
severity |= Logger::Debugging;
// Detach debug messages from you self defined stream
Assimp::DefaultLogger::get()->attachStream( new myStream, severity );

If you want to implement your own logger just derive from the abstract base class #Logger and overwrite the methods debug, info, warn and error.

If you want to see the debug-messages in a debug-configured build, the Logger-interface provides a logging-severity. You can set it calling the following method:

The normal logging severity supports just the basic stuff like, info, warnings and errors. In the verbose level very fine-grained debug messages will be logged, too. Note that this kind kind of logging might decrease import performance.

Assimp::Logger::attachStream
virtual bool attachStream(LogStream *pStream, unsigned int severity=Debugging|Err|Warn|Info)=0
Attach a new log-stream.
scene
const struct aiScene * scene
Definition: Sample_SimpleOpenGL.c:29
aiOrigin
aiOrigin
Seek origins (for the virtual file system API).
Definition: types.h:406
Assimp::IOStream::FileSize
virtual size_t FileSize() const =0
Returns filesize Returns the filesize.
LogSeverity
LogSeverity
Defines the log severity.
Definition: OpenDDLParser.h:87
aiReleaseImport
void aiReleaseImport(const aiScene *pScene)
Definition: Assimp.cpp:266
Assimp::Logger::setLogSeverity
void setLogSeverity(LogSeverity log_severity)
Set a new log severity.
Definition: Logger.hpp:230
Assimp::IOSystem
CPP-API: Interface to the file system.
Definition: IOSystem.hpp:88
IOSystem.hpp
File system wrapper for C++.
Assimp::Logger::VERBOSE
@ VERBOSE
Debug infos will be logged, too.
Definition: Logger.hpp:76
Assimp::Importer::GetErrorString
const char * GetErrorString() const
Returns an error description of an error that occurred in ReadFile().
Definition: Importer.cpp:409
aiImportFile
const aiScene * aiImportFile(const char *pFile, unsigned int pFlags)
Reads the given file and returns its content.
Definition: Assimp.cpp:156
aiReturn
aiReturn
Standard return type for some library functions.
Definition: types.h:376
aiProcess_Triangulate
@ aiProcess_Triangulate
Definition: postprocess.h:125
postprocess.h
Definitions for import post processing steps.
Assimp::Importer::SetIOHandler
void SetIOHandler(IOSystem *pIOHandler)
Supplies a custom IO handler to the importer to use to open and access files.
Definition: Importer.cpp:310
Assimp::IOStream::Write
virtual size_t Write(const void *pvBuffer, size_t pSize, size_t pCount)=0
Write to the file.
aiScene
The root structure of the imported data.
Definition: scene.h:241
testing::internal::string
::std::string string
Definition: gtest-port.h:1097
Assimp::IOSystem::Exists
AI_FORCE_INLINE bool Exists(const std::string &pFile) const
For backward compatibility.
Definition: IOSystem.hpp:263
Assimp::Importer::ReadFile
const aiScene * ReadFile(const char *pFile, unsigned int pFlags)
Reads the given file and returns its contents if successful.
Definition: Importer.cpp:582
scene.h
Defines the data structures in which the imported scene is returned.
Assimp::DefaultLogger::get
static Logger * get()
Getter for singleton instance.
Definition: DefaultLogger.cpp:232
aiProcess_CalcTangentSpace
@ aiProcess_CalcTangentSpace
Definition: postprocess.h:80
Assimp::IOSystem::Open
virtual IOStream * Open(const char *pFile, const char *pMode="rb")=0
Open a new file with a given path.
Assimp::IOStream::Tell
virtual size_t Tell() const =0
Get the current position of the read/write cursor.
aiProcess_SortByPType
@ aiProcess_SortByPType
Definition: postprocess.h:330
Assimp::IOStream::Seek
virtual aiReturn Seek(size_t pOffset, aiOrigin pOrigin)=0
Set the read/write cursor of the file.
Assimp::Logger::info
void info(const char *message)
Writes a info message.
Definition: DefaultLogger.cpp:181
IOStream.hpp
File I/O wrappers for C++.
Assimp::IOSystem::Close
virtual void Close(IOStream *pFile)=0
Closes the given file and releases all resources associated with it.
importer
Assimp::Importer importer
Definition: model_loading.cpp:76
Assimp::IOStream::Flush
virtual void Flush()=0
Flush the contents of the file buffer (for writers) See fflush() for more details.
Importer.hpp
Defines the C++-API to the Open Asset Import Library.
cimport.h
Defines the C-API to the Open Asset Import Library.
Assimp::DefaultLogger::kill
static void kill()
Kills the current singleton logger and replaces it with a #NullLogger instance.
Definition: DefaultLogger.cpp:238
Assimp::IOStream::Read
virtual size_t Read(void *pvBuffer, size_t pSize, size_t pCount)=0
Read from the file.
Assimp::Importer
CPP-API: The Importer class forms an C++ interface to the functionality of the Open Asset Import Libr...
Definition: Importer.hpp:115
Assimp::IOStream
CPP-API: Class to handle file I/O for C++.
Definition: IOStream.hpp:70
Assimp::DefaultLogger::create
static Logger * create(const char *name=ASSIMP_DEFAULT_LOG_NAME, LogSeverity severity=NORMAL, unsigned int defStreams=aiDefaultLogStream_DEBUGGER|aiDefaultLogStream_FILE, IOSystem *io=NULL)
Creates a logging instance.
Definition: DefaultLogger.cpp:133
aiGetErrorString
const char * aiGetErrorString()
Returns the error text of the last failed import process.
Definition: Assimp.cpp:452
aiProcess_JoinIdenticalVertices
@ aiProcess_JoinIdenticalVertices
Definition: postprocess.h:93
Assimp
MACHINE-GENERATED by scripts/ICFImporter/CppGenerator.py.
Definition: 3DSExporter.cpp:57
gtest_output_test.message
tuple message
Definition: gtest_output_test.py:331