![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
view3dscene is a viewer for many 3D model formats: glTF, X3D, VRML, Collada, 3DS, MD3, Wavefront OBJ, STL and (2D) Spine JSON and sprite sheets (in CGE, Cocos2d, Starling XML formats).
Explore the virtual world with collisions, gravity, animations, sensors, shadows, mirrors, shaders and more. You can also convert all models to X3D.
If you already have Castle Game Engine, then just run view3dscene
executable in CGE bin
subdirectory. There's no need to download it separately.
Download also our collection of demo models to test view3dscene!
Documentation:
No installation is required. Just download and unpack these archives wherever
you want, and run the view3dscene
program inside.
Included is also the tovrmlx3d
program,
useful for converting 3D models to X3D in batch (command-line) mode.
This is free/open-source software. Developers can download sources of this program. Or just get the code from GitHub.
Demo scenes: our
demo models contains a lot of interesting models,
you can open them all with view3dscene
.
PLatform-specific notes:
All the 3D and 2D model formats supported by Castle Game Engine can be opened: X3D, VRML, Collada, 3DS, MD3, Wavefront OBJ, Spine JSON...
Various navigation modes are available:
Examine
(easily rotate and move the whole model),
Walk
(walk like in FPS games,
with collision detection, gravity and related features available),
Fly
(similar to Walk
but without gravity),
2D
.
All model formats can be converted to X3D.
You can convert between X3D classic and XML encodings (in both directions), and you can convert from VRML 2 to X3D. You can also use view3dscene as a "pretty-printer", just open and save any X3D or VRML file without any version conversion.
Command-line options to convert in batch mode (--write
)
are available in view3dscene. Special minimized binary
tovrmlx3d
(useful to install on servers without GUI libraries
available) is also included in view3dscene archive.
A number of Castle Game Engine's rendering features are available, like GLSL shaders, bump mapping and shadows.
Built-in ray-tracer (that is also available as a separate command-line program, rayhunter) to generate nice views of the scene (with shadows, mirrors, and transmittance). Classic ray-tracer implements exactly VRML 97 / X3D lighting equations.
You can inspect your model (select triangles by clicking right mouse button in Walk / Fly mode, and use menu item Help -> Selected object information).
There are also very limited editing capabilities. They are intended to be used only as post-processing of some model. We intentionally do not try to implement a full 3D authoring program here.
Animations may be played from VRML / X3D files, using sensors, scripts, interpolators and all other VRML events features.
You can activate VRML pointing-device sensors by clicking with left mouse button (the cursor will change shape and you will get status information when your cursor is over some clickable sensor). Note that this works only when Collision detection is on (as it requires octree).
You can also play a named animation using menu Animation -> Named Animations.
Baked animations can also be played from Castle Animation Frames (castle-anim-frames) format or MD3 files (and you can convert any interactive VRML/X3D animation to a baked one).
There are menu items and command-line options to catch screenshots and movies of 3D scenes and animations. GNOME users will be happy to hear that it can also be used as Nautilus thumbnailer, providing thumbnails when you view directory with VRML / X3D and other 3D models. We can also make a special "screenshot" of 3D environment as a cube map (to DDS, or six separate images).
Left mouse button is used for interacting with the VRML/X3D world. When the cursor turns into a grabbing hand you know you can click or drag on this 3D object. This uses the VRML/X3D pointing-device sensors, and is fully configurable by 3D world authors.
Ctrl + Right mouse click picks a point, selecting a triangle and it's containing shape. The selected point / triangle / shape is then used for some operations, like "Help -> Selected Object Information".
Examine
navigation mode:Mouse: | |
---|---|
Rotate | Left mouse dragging |
Move | Middle mouse dragging (or Left mouse + Shift) |
Zoom | Right mouse dragging (or Left mouse + Ctrl; or scroll wheel) |
Keys: | |
Rotate | Arrows |
Stop rotating | Space |
Move | Ctrl + Arrows |
Scale | + / - |
Walk
/ Fly
navigation modes:Mouse: | |
---|---|
Forward / backward | Drag up / down with left mouse button |
Rotate | Drag left / right with left mouse button |
Move (strafe) left / right | Drag left / right with right mouse button |
Fly up / down | Drag up / down with right mouse button |
Raise / bow your head | Mouse wheel |
Keys: | |
Forward / backward | W / S or Up / Down |
Rotate | Left / Right |
Move (strafe) left / right | A / D |
Jump / Crouch (or fly up / down) | Space / C |
Run | Shift |
Turn Mouse Look On
(Ctrl+M) to look around by moving the mouse. It is usually comfortable to combine it with movement using AWSD keys. | |
Additional controls: | |
Increase / decrease moving speed | + / - |
Increase / decrease avatar height (preferred camera height above the ground) | Insert / Delete |
Rotate slower (useful to precisely set the camera) | Ctrl + Left / Right |
We also support 3D mouse devices, see the demo video about 3D mouse inside view3dscene.
There are many more operations with key shortcuts, that work in all navigation modes. Just explore the view3dscene menu, and look at the key shortcuts.
All options described below may be given in any order. They all are optional.
Command-line options:
--screenshot TIME FILE-NAME --screenshot-range TIME-BEGIN TIME-STEP FRAMES-COUNT FILE-NAME
These options allow you to capture a screenshot of the loaded scene. They know about animations stored in 3D files, that's why they take parameters describing the animation time to capture. They are used to take screenshots in "batch mode". (In interactive mode, you can use comfortable menu items Display -> Screenshot....)
For a still 3D scene, you usually just want to use the simpler
--screenshot
option with TIME
set to anything (like zero) and not worry about anything else.
For animations, more possibilities are available. You can capture
any frames of the animation by using many --screenshot
options.
You can also capture a movie by --screenshot-range
(as a series of images or, if
ffmpeg is installed and
available on $PATH, even directly to a single movie file).
The biggest advantage of recording movie this way
is that the movie is guaranteed to be captured with stable number
of frames per second. This is different than using
some independent programs to capture OpenGL output, like
the fine GLC
(nice GLC overview here),
as real-time capture usually means that the program
runs slower, and often you loose movie quality.
You most definitely want to pass 3D model file to load at command-line too, otherwise we'll just make a screenshot of the default empty (black) scene. So to take a simple screenshot of a scene, at it's default camera, just call
view3dscene my_model.wrl --screenshot 0 output.png
The detailed specification how screenshot options work:
First of all, after all the --screenshot
and --screenshot-range
options are processed,
view3dscene exits. So they work in "batch mode".
The --screenshot TIME FILE-NAME
simply saves
the screenshot at time TIME
to an image file FILE-NAME
.
Image format is guessed from FILE-NAME
extension,
see castle-view-image for detailed list of image formats that we can handle.
In short, we handle many popular image formats, like PNG and JPG,
and these are what usually you want to use.
The --screenshot-range TIME-BEGIN TIME-STEP FRAMES-COUNT FILE-NAME
option takes FRAMES-COUNT
screenshots. The first screenshot
is at time TIME-BEGIN
, second screenshot is at
TIME-BEGIN + TIME-STEP
, next one is at
TIME-BEGIN + 2 * TIME-STEP
... you get the idea.
The FILE-NAME
is either
A movie filename. This must have a recognized movie MIME type (for local files, MIME type is just recognized from extension), this includes:
Please report if we miss some MIME type (and file extension) above, it's trivially easy to add all formats supported by ffmpeg. Availability of all these video formats may depend on installed ffmpeg codecs.
ffmpeg must be installed and available on $PATH for this to work.
FILE-NAME
may also be a pattern to generate
names of images to save, like @counter(4).png
.
Details about using filename patterns are below (although you
can probably already guess how it works :) ).
All filenames for both screenshot options may specify a pattern
instead of an actual filename. A pattern is simply a filename
with macro @counter(<padding>)
inside, when capturing @counter(4)
will be replaced by the current screenshot number (padded with zeros to 4 digits).
For capturing a series of images
by --screenshot-range
it's even required to specify
a pattern with @counter(<padding>)
(since capturing
a number of images to a single image file has no point...). But
it's also allowed in all other cases, even a movie filename
may also be a pattern with @counter(<padding>)
sequence,
in case you want to use multiple --screenshot-range
options to get multiple auto-named movies.
The precise description how @counter(<padding>)
works:
All --screenshot
and --screenshot-range
options are processed in order.
When a filename with pattern @counter(<padding>)
is found, we replace all
@counter(<padding>)
occurrences in this filename with current counter value
and increment the counter. For --screenshot-range
with
an image pattern, we do this for every single frame.
The counter starts at 1.
The parameter of @counter(<padding>)
is the padding.
For example, @counter(1)
results in names like
1, 2, ..., 9, 10... while @counter(4)
results in names like 0001, 0002, ..., 0009, 0010, ...
Add --screenshot-transparent
option to have a transparent image,
with transparent pixels in place where background color would be visible.
Examples:
Simply get a single screenshot at given time:
view3dscene my_model.wrl --screenshot 0 output.png
Simply get a movie of 2 seconds of animation. To calculate the numbers, note that we generate a movie with 25 frames per second:
view3dscene my_model.castle-anim-frames --screenshot-range 0 0.04 50 output.avi
To get this as a sequence of images, just use output@counter(4).png
instead of output.avi
.
Example of more complicated use:
view3dscene my_model.castle-anim-frames \ --screenshot-range 0 0.04 50 output@counter(1).avi \ --screenshot-range 10 0.04 50 output@counter(1).avi
This generates two files: output1.avi
with 2 second animation
from 0.0 to 2.0 time, and output2.avi
with 2 second animation
from 10.0 to 12.0 time.
Hints:
To control the look of your screenshot, you often want to
use VRML/X3D nodes like Viewpoint
, NavigationInfo
,
Background
. For example, take a look at
this sample VRML file.
You can use --viewpoint
command-line option (see below)
to choose a different viewpoint for screenshot.
You can generate wanted Viewpoint
node
also by using view3dscene, just set your camera (in interactive mode)
the way you like and use menu item
Console -> Print Current Camera Node.
To control the size of resulting screenshot, just use
--geometry
command-line parameter
(documented at standard options
understood by our OpenGL programs).
For example, take a look at
mk_screenshot_for_kambi_www.sh
script.
To make your screenshot look best, you may want to use anti-aliasing,
see --anti-alias
option below.
Take a look at the example how to make a screenshot from animation in screenshot_for_kambi_www/ directory.
To take a screenshot on a stripped-down Unix server, please bear in mind that you need to install a graphic environment (that is, X Windows and OpenGL) on your server. Even in batch mode, we still use OpenGL to grab the screenshot images (because using off-screen Mesa or our toy ray-tracer doesn't result in a really nice output; we really want OpenGL for all those GLSL effects and such).
Normally, you also need GTK libraries installed. However, you can compile from sources a version of view3dscene that doesn't need these libraries, and directly accesses XWindows. It will miss a menu bar and some other nice GUI stuff, but that's not a problem if you only want to run it in batch mode for screenshots. To do this:
castle_game_engine/
and view3dscene/
directories are siblings.
export CASTLE_FPC_OPTIONS=-dCASTLE_WINDOW_XLIB cd view3dscene/ ./compile.sh # and copy resulting view3dscene (and tovrmlx3d) binaries wherever you want
On a server, you probably want to initialize taking a screenshot from a script, and your script isn't necessarily running within the X server. There are basically two solutions to this:
You can keep the X server running continuously,
and keep your user logged in to the X server,
and instruct view3dscene to connect to your running X server.
You do this by adding --display=:0
option
to the view3dscene command-line (where :0
is a common example; for details,
see X manuals). Or you can set and export the DISPLAY
environment variable, like export DISPLAY=:0
.
Unfortunately, this method sometimes doesn't work.
On some systems, the view3dscene will get an OpenGL context without
a FrameBuffer (long story short, it means that you cannot capture
the screen without actually seeing the window) and the resulting screenshot
will be pure black (or garbage).
On other systems, there is a problem with glXChooseVisual
that may hang until you actually switch the current terminal
to the X server.
The other approach, more reliable in my experience
(please share your own experience
on the forum) is to create new X server along with running
view3dscene, by using xinit
. See man xinit
for full
details, in short use something like xinit /full/path/to/view3dscene my_model.x3d --screenshot 0 /tmp/output.png -- :1
. The important thing
is to specify the full path of the view3dscene binary (otherwise xinit
only adds the arguments to some useless default xterm command-line). Adding -- :1
at the end is only necessary if the default display (:0
)
may be already taken. xinit
will create an X server
with new display name, run view3dscene, and exit immediately
when view3dscene exits (which should be as soon as a screenshot is done).
In interactive mode, you can use view3dscene menu items File -> Save As.. to save (converting if needed) all 3D model formats to X3D or VRML.
Most formats glTF 2.0, Collada, Spine JSON, 3DS, MD3, Wavefront OBJ, GEO, sprite sheets are always converted to X3D.
Formats Inventor, VRML 1.0, VRML 2.0, X3D can be saved back to their original format. In this case, view3dscene is simply a "pretty-printer", exactly preserving all the information inside the file, only reformatting your content and removing the comments.
VRML 2.0 can be also converted to X3D.
Conversion from VRML 2.0 to X3D is mostly trivial. There are some different keywords between VRML 2 and X3D, but generally X3D is simply a superset of everything that VRML 2 has.
You can also change the X3D encoding (from classic to XML or the other way around). Changing encoding is a lossless operation, as the same nodes graph can be exactly expressed in both encodings.
All these conversions can be also performed in batch mode
by command-line options described below. You can either use view3dscene with --write
option, or you can use separate binary tovrmlx3d
.
Separate tovrmlx3d
may be sometimes more desirable,
as it's smaller, not linked with any GUI libraries (so it will work
even on a stripped-down system) and has simpler command-line options
(as it's purpose is only to convert).
Examples:
# Convert Collada to X3D view3dscene input.dae --write > output.x3dv # Same as above, but by tovrmlx3d binary tovrmlx3d input.dae > output.x3dv # Convert VRML 2.0 to X3D in classic encoding. # You could add --encoding=classic, but it's not needed # (it is the default anyway). view3dscene input.wrl --write --write-force-x3d > output.x3dv # Same as above, but by tovrmlx3d binary tovrmlx3d input.wrl --force-x3d > output.x3dv # Convert VRML 2.0 to X3D in XML encoding. # You could add --[write-]force-x3d, but it's not needed # (it is implied by XML encoding anyway). view3dscene input.wrl --write --write-encoding=xml > output.x3d # Same as above, but by tovrmlx3d binary tovrmlx3d input.wrl --encoding=xml > output.x3d
Detailed docs of view3dscene
command-line options for converting:
Do not open any window,
only write the 3D model to the standard output and exit.
Other --write-xxx
options affect the generated output.
Choose encoding of the output file. By default, we use classic encoding.
This option is meaningful only when --write
option is also used.
Force output to be an X3D file. This is really useful only when input model is VRML 2.0.
Conversion to X3D is also automatically forced (no need to specify it explicitly
by this option) if the chosen encoding is XML
(that is, you used --write-encoding=xml
).
That's because only X3D supports XML encoding.
Summarizing, you only need to use this option when you want to convert VRML 2 to X3D in classic encoding.
When this is used on VRML 1.0 or Inventor models, we'll also convert parts of them to X3D. But the result is not really useful: you will get a file encoded using X3D keywords, but using VRML 1.0/Inventor node names. Real conversion from VRML 1.0/Inventor to X3D is not implemented (yet).
This has no effect when used on 3D models that are already X3D, or that can be only output as X3D (Collada, 3DS, etc.).
This option is meaningful only when --write
option is also used.
Do not use Castle Game Engine extensions to X3D.
For example we will not use Tangent
, flipVertically
,
gravityTransform
in the generated X3D when importing glTF.
This makes X3D output valid (but a little less functional)
and suitable for other X3D browsers.
This option works at loading, and it is meaningful regardless
of whether you used --write
.
Both view3dscene
and tovrmlx3d
have this option.
tovrmlx3d
has analogous options for converting,
but without the write-
prefix (as tovrmlx3d
is only useful for converting). More precisely:
tovrmlx3d
always reads input 3D model (from filename given on a command-line),
and outputs it on standard output as VRML/X3D.
--encoding=classic|xml
instructs to use given encoding.
See --write-encoding=classic|xml
docs above.
--force-x3d
instructs to force X3D conversion.
See --write-force-x3d
docs above.
Hide the top menubar. Useful for full-screen presentations.
Use full-screen anti-aliasing. You can also configure it from
the menu File -> Startup Preferences -> Anti aliasing.
Using this command-line option is mainly useful together with
--screenshot
option.
Argument AMOUNT
is an integer >= 0. Exact 0 means "no anti-aliasing", this is the default.
Each successive integer generally makes method one step better.
But also more demanding — program may run slower
(if your graphic card cannot provide context with sufficient number of samples
needed for multi-sampling). See Anti aliasing in interactive mode
for the meaning of AMOUNT
values.
Currently, highest value is 4. So AMOUNT
numbers above 4 are
exactly the same as 4.
There is no guarantee what specific values of AMOUNT
exactly
mean, as this depends on your graphic card capabilities. The graphic cards
themselves don't provide methods to reliably set some specific FSAA method
(only hints, like glHint(GL_MULTISAMPLE_FILTER_HINT_NV, ...)
)
since the general idea is that better GPU models may provide the same or even
better results using different methods. From your (user) point of view,
you can test each method and just decide which looks best and isn't too slow
on your 3D model and graphic card.
Specifies the name or a number of the viewpoint that will be bound (used) when the scene is loaded.
By default, when this option is not used, we follow VRML/X3D standard and use the first viewpoint found in the file (but not in the inlined files). Of course you can always add nodes to the scene to trigger binding other viewpoints at the beginning (for example, add ProximitySensor
with very large size that sends the enter
event to the set_bind
of chosen viewpoint). Or you can just exchange the order of viewpoint nodes. But sometimes it's not comfortable to edit the scene. Especially if you want to use the --screenshot
options to capture a scene, it's useful to be able to choose a viewpoint by this command-line option.
If you use this option: when the given VIEWPOINT-NAME
is a number, it is treated as the index of viewpoint to be used (0 means the first viewpoint, 1 means the 2nd viewpoint and so on). Otherwise, VIEWPOINT-NAME
is treated as a node name (node name is given by "DEF Xxx"
in VRML/X3D, and it cannot start with a digit, so this is unambigous).
In interactive mode, remember that you don't need this option — instead you can use comfortable Navigation -> Viewpoints menu.
As usual all standard options understood by
OpenGL programs,
OpenAL (3D sound) programs,
all programs
are also allowed. Run with command-line --help
to get full list.
To play movies (in VRML/X3D MovieTexture
nodes) and
to record movies (by --screenshot-range
option)
you have to install ffmpeg
and make sure it's available on $PATH.
ffmpeg
package
suitable for their distribution.
ffmpeg
using
HomeBrew,
MacPorts or
Fink.