F3D 3.0.0 Migration Guide

[mwestphal]

F3D 3.0.0 Migration Guide

Deprecation removal

First make sure any deprecated CLI options, API or options are not used when using F3D 2.5.1.
If they are, replace them by modern usage as recommend in the errors and warnings.

For F3D users

CLI Options changes

= should be used for CLI options values

Add a = for all long option values if not already, eg:
--light-intensity 0.6 -> --light-intensity=0.6

--scalars CLI options replaced

--scalars has been replaced by two CLI options.
To turn on scalar coloring use --scalar-coloring. To select the array to color with use --coloring-array=array, eg:

--scalars=Normals -> --scalar-coloring --coloring-array=Normals

The short option -s can still be used to turn on scalar coloring.

--geometry-only has been removed

It is not supported to load only the geometry using --geometry-only. If this is a needed feature you can disable the texture individually by setting them to the empty string, eg: --texture-base-color=

--group-geometries has been replaced with --multi-file-mode

The way files are loaded in F3D has been completely reworked and is now way more flexible.
The CLI option has changed though, eg:
--group-geometries -> --multi-file-mode=all

Multiple rendering backends are available, osmesa is another possible choice for headless rendering. Use --list-rendering-backends for the complete list.

Simple CLI option renaming:

--dry-run -> --no-config
--animation-frame-rate -> frame-rate
--bg-color -> --background-color
--comp -> --coloring-component
--progress -> --loading-progress
--cells -> --coloring-by-cells
--range -> --coloring-range
--bar -> --coloring-scalar-bar
--inverse -> --volume-inverse
--samples -> --raytracing-samples
--denoise -> --raytracing-denoise
--ref -> --reference
--ref-threshold -> --reference-threshold
--readers-list -> --list-readers

Other changes

Esc is now Ctrl+Q to quit the application

Pressing Esc is now used by the console, so quitting F3D now is Ctrl+Q.
If needed, you can change that in your configuration file, however closing the console will always be Esc.

? interaction has been removed

The ? interaction has been removed, use the console and type print_scene_info, print_coloring_info, print_mesh_info or print_options_info to print such info.

If needed you can add a interaction bind for these commands in your configuration file.

No headless binary release anymore

There is no headless binary anymore, just use the standard binary with the --rendering-backend CLI option, eg:
--rendering-backend=egl.

For libf3d users

API changes

options

The options API has been completely reworked and now offers three different API as documented here.

Code using v2.5.1 should be able to rely on the variant API however we recommend using the struct API for better integration in IDE or the string API for flexibility.

eg:

opt.set("render.show_edges", true);

Should now be either:

opt.render.show_edges = true;

or

opt.setAsString("render.show_edges", "true");

engine

Engine creation has been completely reworked and now requires the usage of dedicated static creation method, eg:

f3d::engine eng();

Should now be:

f3d::engine eng = f3d::engine::create();

engine::libInformation was also reworked.

loader -> scene

The loader class has been reworked into the scene class and both loadGeometry and loadScene have been replaced by scene::add, eg:

eng.getLoader().loadScene("path/to/file.ext"); or eng.getLoader().loadGeometry("path/to/file.ext");

Should now be:

eng.getLoader().add("path/to/file.ext");

Loading multiple files is supported by the add method, use scene::clear to remove them all.

interactor

interactor has been completely reworked for more flexibility and simplicity.

setKeyPressCallBack and setDropFilesCallBack have been removed, use the command and binding API instead.

timerCallback API has been removed, use interactor::start with a callback and time delta argument instead.

camera

camera API has been renamed simply:

pos -> position
up -> viewUp
foc -> focalPoint
angle -> viewAngle

image::compare

image::compare now directly returns the error value, eg:

double error;
if (img.compare(img2, 0.05, error))

Should be:

if (img.compare(img2) >= 0.05)

other API changes

C++17 is now required to use the libf3d and [[nodiscard]], std::string_view and std::filesystem::path are now used in the whole API. This should not cause any problem not easily caught by build error and warnings. You may want to migrate to std::filesystem::path.

If your compiler does not support C++17, please use F3D 2.5.1 until it does.

Options renaming

opt.model.scivis.array_name

opt.model.scivis.array_name has been split into opt.model.scivis.enable and opt.model.scivis.array_name.
Only setting opt.model.scivis.array_name does not enable scivis coloring anymore*.

Simple option renaming

render.background.blur -> render.background.blur.enable
render.background.blur_coc -> render.background.blur.coc
interactor.axis -> ui.axis

Optional options

Many options are now std::optional with the option not set meaning the no action should be taken, see options.json, options.h and the options documentation.