# libf3d

libf3d is a BSD-licensed C++17 library to open and render 3D meshes. It is of course used by F3D.
libf3d API is simple and easy to learn. Python bindings are provided through pybind11. Java bindings are also available.

## Getting Started

Rendering a file and starting the interaction is very easy:

```cpp
#include <f3d/engine.h>
#include <f3d/interactor.h>
#include <f3d/scene.h>

// Load VTK native readers
f3d::engine::autoloadPlugins();

// Create a f3d::engine
f3d::engine eng = f3d::engine::create();

// Add a file into a scene
eng.getScene().add("path/to/file.ext");

// Start rendering and interacting
eng.getInteractor().start();
```

As well as loading multiple files:

```cpp
#include <f3d/engine.h>
#include <f3d/interactor.h>
#include <f3d/scene.h>

// Load VTK native readers
f3d::engine::autoloadPlugins();

// Create a f3d::engine
f3d::engine eng = f3d::engine::create();

// Load multiples geometries
eng.getScene().add({"path/to/file.ext", "path/to/file2.ext"});

// Start rendering and interacting
eng.getInteractor().start();
```

It's also possible to load a geometry from memory buffers:

```cpp
#include <f3d/engine.h>
#include <f3d/interactor.h>
#include <f3d/scene.h>

// Create a f3d::engine
f3d::engine eng = f3d::engine::create();

// Create a single triangle
f3d::mesh_t mesh = {};
mesh.points = { 0.f, 0.f, 0.f, 0.f, 1.f, 0.f, 1.f, 0.f, 0.f };
mesh.face_sides = { 3 };
mesh.face_indices = { 0, 1, 2 };
eng.getScene().add(mesh);

// Start rendering and interacting
eng.getInteractor().start();
```

It's also possible to visualize your meshes directly from memory without copy, by deriving the `mesh_view` class, making visualization with libf3d fast and with limited additional memory overhead.
It supports any polygonal meshes, with animation and scalar values on points or faces.
An example can be found in `examples/libf3d/cpp/in-situ` folder.

```cpp
#include <f3d/engine.h>
#include <f3d/interactor.h>
#include <f3d/mesh_view.h>
#include <f3d/scene.h>

// Create a f3d::engine
f3d::engine eng = f3d::engine::create();

// Derive f3d::mesh_view
class CustomMesh : public f3d::mesh_view
{
public:
  std::array<double, 2> getTimeRange() const override
  {
    return { 0.0, 10.0 };
  }

  f3d::mesh_view::memory_view_t getMemoryView(double time) const override
  {
    f3d::mesh_view::memory_view_t memoryView = { /* map your data memory here */ };
    return memoryView;
  }
};

eng.getScene().add(std::make_shared<CustomMesh>());

// Start rendering and interacting (press space to start animation)
eng.getInteractor().start();
```

Manipulating the window directly can be done this way:

```cpp
#include <f3d/engine.h>
#include <f3d/image.h>
#include <f3d/scene.h>
#include <f3d/window.h>

// Load VTK native readers
f3d::engine::autoloadPlugins();

// Create a f3d::engine with a offscreen window
f3d::engine eng = f3d::engine::create(true);

// Load a geometry
eng.getScene().add("path/to/file.ext");

// Set the window size and render to an image
f3d::image img = eng.getWindow().setSize(300, 300).renderToImage();

// Save the image to a file
img.save("/path/to/img.png");
```

Changing some options can be done this way:

```cpp
#include <f3d/engine.h>
#include <f3d/interactor.h>
#include <f3d/options.h>
#include <f3d/scene.h>

// Load VTK native readers
f3d::engine::autoloadPlugins();

// Create a f3d::engine
f3d::engine eng = f3d::engine::create();

// Recover the options and set the wanted value
f3d::options& opt = eng.getOptions();
opt.render.effect.ambient_occlusion = true;
opt.render.effect.antialiasing.mode = "fxaa";

// Standard libf3d usage
eng.getScene().add("path/to/file.ext");
eng.getInteractor().start();
```

Most options are dynamic, some are only taken into account when loading a file. See the [options](03-OPTIONS.md) documentation.

Find more examples in the [examples directory](https://github.com/f3d-app/f3d/tree/master/examples),
you can also find other usages in the [testing directory](https://github.com/f3d-app/f3d/tree/master/library/testing).

For the complete documentation, please consult the [libf3d doxygen documentation.](https://f3d.app/docs/next/category/libf3d-api-reference).

## Building against the libf3d

> [!NOTE]
> `libf3d` works best when built as a shared library, make sure it's the case. The `sdk` component must also be installed in order to be able to use CMake to find `libf3d`.
> eg: `cmake --install <build_dir> --component sdk`

It's as simple as linking against it like this in your CMakeLists.txt:

```cmake
find_package(f3d REQUIRED COMPONENTS library)
[...]
target_link_libraries(your_target f3d::libf3d)
```

## find_package COMPONENTS

When using `find_package(f3d)` and `sdk` CMake component have been installed, you can require specific components:

- `application`: access to f3d::f3d target
- `library`: access to f3d::libf3d target and include dir
- `plugin_sdk`: access to CMake macros to create plugins, the f3d::vtkext target and include dir

see the installed `f3dConfig.cmake` file for more info.

## Extending libf3d with plugins

In order to add new supported file format to libf3d, you can create a plugin using CMake macros. Please follow instructions in the [F3D plugin SDK guide](05-PLUGINS.md).
Also make sure the `plugin_sdk` component have been installed as well as the `sdk` component.

## Migrate from v3.5

Non backward compatible changes have been introduced in v4.0, please take a look at [the migration guide](06-MIGRATION.md) if you are trying to migrate your libf3d v3.5 code base.