1%% Part of Stellarium User Guide 0.15+ 2%% History: 3%% 2016-04-12 adapted from Scenery3D plugin documentation. Just reformatted. 4%% Doc should be edited in here from now on. 5%% 2017-12-09 update about performance after playing with big models. Added section about temporally changing material. 6%% 2019-10-11 added current references 7%% !!!!!!!!!! Please ask GZ before editing this file. !!!!!!!!!!!!!!! 8 9\chapter{Scenery3d -- 3D Landscapes} 10\label{ch:scenery3d} 11\chapterauthor*{Georg Zotti and Florian Schaukowitsch} 12 13 14\section{Introduction} 15\label{sec:scenery3d:Introduction} 16 17 18Have you ever wished to be able to walk through Stonehenge or other 19ancient building structures described as being constructed with 20astronomical orientation in mind, and experience such orientation in a 213D virtual environment that also provides a good sky simulation? 22 23The Stellarium Scenery3d plugin allows you to see architectural 3D models 24embedded in a landscape combined with the excellent representation of the sky 25provided by Stellarium. You can walk around, check for (or 26demonstrate) possible astronomical alignments of ancient architecture, see 27sundials and other shadow casters in action, etc. 28 29\section{Usage} 30\label{sec:scenery3d:Usage} 31 32 33You activate the plugin with the \emph{circular enclosure} button \guibutton{0.6}{bt_scenery3d_off.png} at screen 34bottom or by pressing \key{\ctrl+W}. A right-click on that button \newFeature{0.21.2} (or \key{\ctrl+\shift+W}) 35opens the settings dialog. Once loaded and 36displaying, you can walk around pressing \key{\ctrl} plus cursor keys. Change eye 37height with \key{\ctrl+Page\,\arrowkeyup\,}/\key{\ctrl + Page\,\arrowkeydown\,} keys. Adding \key{\shift} key increases speed by 10, 38adding \key{\Alt} multiplies by 5 (pressing both keys multiplies by 50!). If you release \key{\ctrl} before 39the cursor key, animation will continue. (Press \key{\ctrl}+any cursor key to stop 40moving.) 41%\footnote{I (GZ) had to change keyboard handling in the main program, somewhat breaking the plugin concept.} 42 43Further key bindings exist which can be configured using the Stellarium default 44key-binding interface. Some options are also available in the Scenery3d dialog. 45For example, coordinate display can be enabled with \key{\ctrl+R}+\key{T}. If your models are georeferenced 46in a true geographical coordinate grid, e.g.\ UTM or Gauss-Krueger, you will 47especially like this, and this makes the plugin usable for scientific purposes. 48Display shows grid name, Easting, Northing, Altitude of ground, and eye height 49above ground. 50 51Other features include a virtual ``torchlight'', which can be enabled with \key{\ctrl+R}+\key{L} to give 52additional local illumination around the viewer to help to see in the dark. 53Interesting points of view can be saved and restored later by the user, 54including a description of the view. Scene authors can also distribute 55predefined viewpoints in their scene. 56 57The plugin also simulates the shadows of the scene's objects cast by 58the Sun, Moon and even Venus (only 1 shadow caster used at a time, you 59will never see shadows cast by Venus in moonlight), so you could use 60it for examining sundials, or analyze and simulate light-and-shadow 61interactions in archaeological structures. 62 63\section{Hardware Requirements \& Performance} 64\label{sec:scenery3d:HardwareRequirements} 65 66In order to work with the non-linear projection models in Stellarium, 67this plugin uses a trick to create the foreground renderings: it 68renders the scene into the six planes of a so-called cubemap, which is 69then correctly reprojected onto the sides of a cube, depending on the 70current projection settings. Your graphics card must be able to do 71this, i.e. it must support the OpenGL extension called 72\texttt{EXT\_framebuffer\_object}. Typical modern 3D cards (by Nvidia 73or ATI/AMD) support this extension. In case your graphics hardware 74does not suppport it, the plugin will still work, but you are limited 75to perspective projection. 76 77You can influence rendering quality, but also speed, using the plugin's 78GUI, which provides some options such as enabling the use 79of shadows, bumpmapping (provides more realistic surface lighting) or 80configuring the sizes of the textures used 81for the cubemap or shadowmaps. Larger values there improve the quality, 82but require faster hardware and more video memory for smooth results. 83 84Because the ``cubemap trick'' requires quite a large amount of performance (in 85essence, the scene has to be rendered 6 times), there are some options available 86that try to reduce this burden. The first option is to change the type of the 87``cubemap''. The most compatible setting is \emph{6 textures}, which seems to 88work best on older integrated Intel GPUs. The recommended default is the second 89setting, \emph{Cubemap}, which uses a more modern OpenGL feature and generally 90works a bit faster than \emph{6 textures} on more modern graphics cards. Finally, 91the \emph{Geometry shader} option tries to render all 6 cube faces at once. This 92requires a more recent GPU + drivers (at least OpenGL 3.2 must be supported), 93the setting is disabled otherwise. Depending on your hardware and the scene's 94complexity, this method may give a speedup or may be slower, you must find this out yourself. 95 96Another option prevents re-rendering of the cubemap if nothing relevant has 97changed. You can define the interval (in Stellarium's simulation time) in which 98nothing is updated in the GUI. You can still rotate the camera without causing a 99re-draw, giving a subjective performance that is close to Stellarium's 100performance without Scenery3d. When moving, the cubemap will be updated. You can 101enable another option that only causes 1 or 2 sides of the cubemap to be updated 102while you move, giving a speedup but causing some parts of the image to be 103outdated and discontinuous. The cubemap will be completed again when you stop 104moving. 105 106Shadow rendering may also cause quite a performance impact. The \emph{Simple 107shadows} option can speed this up a lot, at the cost of shadow quality 108especially in larger scenes. Another performance/quality factor is shadow 109filtering. The sharpest (and fastest) possible shadows are achieved with 110filtering \emph{Off}, but depending on shadowmap resolution and scene size the 111shadows may look quite ``blocky''. \emph{Hardware} shadow filtering is usually 112very fast, but may not improve appearance a lot. Therefore, there are additional 113filter options available, the \emph{High} filter option is relatively expensive. 114Finally, the \emph{PCSS} option allows to approximate the increase of solar and lunar shadow 115penumbras relative to the distance from their shadow casters, i.e. shadows are 116sharp near contact points, and more blurred further away. This again requires 117quite a bit of performance, and only works if the shadow filter option is set to 118\emph{Low} or \emph{High} (without \emph{Hardware}). 119 120The configuration GUI shows tooltips for most of its settings, which can explain 121what a setting does. All settings are saved automatically, and restored when you 122reopen Stellarium. 123 124 125\subsection{Performance notes} 126\label{sec:scenery3d:Performance} 127 128This plugin clearly runs better with proper 3D graphics cards. 129On reasonably good hardware 130%2012: (tested on a notebook PC with Nvidia M9800 GTS), 131% models up to 100.000 triangles are fluent, up to 250.000 are still ``interactive''. 132% we have 2015, and a much faster implementation! 133%%(tested on a notebook PC with Nvidia M580 GTS), models with about 850.000 triangles 134%% Latest benchmark... 135(tested on a notebook PC with Nvidia M960), models with over 10.000.000 triangles 136%% 137are working nicely with shadows and bumpmaps, although your mileage may vary. On very small 138hardware like single-board computers with native OpenGL ES2, models 139may be limited to 64k vertices (points). If display is too slow, 140switch to perspective projection: all other projections require almost 141sixfold effort! Or try the ``lazy'' cubemap mode and lazy updates of tiles, 142where the scene is only rendered in specific timesteps or 143when movement happens. 144 145 146\section{Model Configuration} 147\label{sec:scenery3d:ModelConfiguration} 148 149The model format supported in Scenery3d is Wavefront .OBJ, which is 150pretty common for 3D models. You can use several modeling programs to 151build your models. Software such as \program{Blender}, \program{Maya}, \program{3D Studio 152Max} etc.\ can export OBJ. 153 154\subsection{Exporting OBJ from Sketchup} 155\label{sec:scenery3d:sketchup} 156 157A simple to use and cost-free modeling program is \program{Sketchup}, commonly 158used to create the 3D buildings seen in \program{Google Earth}. It can be used 159to create georeferenced models. OBJ is not a native export format for 160the standard version of \program{Sketchup}. If you are not willing to 161afford \program{Sketchup Pro}, you have to find another way to export a textured 162OBJ model. 163 164 165\begin{table}[t] 166 \centering 167\begin{tabular}{rl}\toprule 168Geometry&Yes\\Lights&Yes\\Clay&No\\Photomatched&Yes\\DefaultUVs&No\\Instanced&No\\\bottomrule 169\end{tabular} 170\caption{Kerkythea Export Settings} 171 \label{fig:scenery3d:KerkytheaExportSettings} 172\end{table} 173 174One good exporter is available in the \program{Kerkythea} renderer project\footnote{ 175Available at \url{http://www.kerkythea.net/cms/}}. You need 176\program{SU2KT~3.17} 177or better, and \program{KT2OBJ~1.1.0} or better. Deselect any selection, then 178export your model to the \program{Kerkythea} XML format with settings shown in 179\ref{fig:scenery3d:KerkytheaExportSettings}. 180(Or, with selection enabled, make sure settings are No-Yes-Yes-No-Yes-No-No.) 181You do not have to launch \program{Kerkythea} unless you want to create nice renderings of 182your model. 183Then, use the \program{KT2OBJ} converter to create an OBJ. You can delete the 184XML after the conversion. Note that some texture coordinates may not be 185exported correctly. The setting \texttt{Photomatched:Yes} seems now to have 186corrected this issue, esp. with distorted/manu\-ally shifted textures. 187 188Another free OBJ exporter has been made available by 189TIG: \file{OBJexporter.rb}\footnote{Available from 190\url{http://forums.sketchucation.com/viewtopic.php?f=323&t=33448}}. 191This is the only OBJ exporter tested so far capable of handling large TIN landscapes 192($>450.000$ triangles). 193As of version 2.6 it seems to be the best OBJ exporter available for \program{Sketchup}. 194 195%As of version 1.6 it appears to have valid texture coordinates, but I have 196%experienced problems with black faces which need more 197%investigation. Maybe you can combine two OBJ files with another 3D 198%editor after creating individual OBJs if this is a problem. 199 200This exporter swaps Y/Z coordinates, but you can add a key to the config file to 201correct swapped axes, see below. Other exporters may also provide coordinates in 202any order of X, Y, Z -- all those can be properly configured. 203 204Another quirk has to be fixed manually though: in the material description file (MTL), TIG's exporter writes both \texttt{d} and \texttt{Tr} lines with the same value. 205Actually, $\mathtt{Tr}=1.0-\mathtt{d}$ according to OBJ/MTL documentation, so you should edit away one line, or else the later line overwrites the value given earlier. 206Moreover, given that \texttt{Tr=1} should actually specify fully transparent objects, such a line will make your object entirely invisible! 207 208Another (almost) working alternative: \file{ObjExporter.rb} by author 209Honing. Here, export with settings \texttt{0xxx00}. This will not create a 210\file{TX...} folder but dump all textures in the same directory as the OBJ 211and MTL files. Unfortunately, currently some material assignments seem to be 212bad. 213 214%Yet another exporter, \file{su2objmtl}, does also not provide good texture 215%coordinates and cannot be recommended at this time. 216 217\subsection{Notes on OBJ file format limitations} 218\label{sec:scenery3d:OBJlimitations} 219 220The OBJ format supported is only a subset of the full OBJ format: Only 221(optionally textured) triangle meshes are supported, i.e., only lines containing 222statements: \parameter{mtllib}, \parameter{usemtl}, \parameter{v}, \parameter{vn}, \parameter{vt}, \parameter{f} 223(with three elements only!), \parameter{g}. Negative vertex numbers (i.e., a 224specification of relative positions) are not supported. 225 226A further recommendation for correct illumination is that all vertices should 227have vertex normals. \program{Sketchup} models exported with the \program{Kerkythea} or TIG plugins 228should have correct normals. If your model does not provide them, default 229normals can be reconstructed from the triangle edges, resulting in a faceted 230look. 231 232If possible, the model should also be triangulated, but the current loader may 233also work with non-triangle geometry. 234%% TODO: GZ: Does that mean Quads, or higher-level polygons? 235The correct use of objects (\parameter{o}) and groups (\parameter{g}) 236will improve performance: it is best if you pre-combine all objects 237that use the same material into a single one. The loader will try to 238optimize it anyways if this is not the case, but can do this only 239partly (to combine 2 objects with the same material into 1, it 240requires them to follow directly after each other in the OBJ). A 241simple guide to use 242\program{Blender}\footnote{\url{https://www.blender.org}} for this task 243follows: 244 245\begin{enumerate} 246\item \menu{File>Import>Wavefront .obj} - you may need to change the forward/up axes for correct orientation, try ``-Y forward'' and ``Z up'' 247\item Select an object which has a shared material 248\item Press \key{\shift+L} and select 'By Material' 249\item Select 'Join' in the left (main) tool window 250\item Repeat for other objects that have shared materials 251\item Export the .obj, making sure to select the same forward/up axes as in the import, also make sure ``Write Normals'', ``Write Materials'' and ``Include UVs'' are checked 252\end{enumerate} 253 254\noindent For transparent objects (with a \parameter{d} or \parameter{Tr} value, alpha testing does 255NOT need this), this recommendation does NOT hold: for optimal 256results, each separate transparent object should be exported as a 257separate ``OBJ object''. This is because they need to be sorted during 258rendering to achieve correct transparency. If the objects are combined 259already, you can separate them using \program{Blender}: 260 261\begin{enumerate} 262\item Import .obj (see above) 263\item Select the combined transparent object 264\item Enter ``Edit'' mode with \key{\tab} and make sure everything is selected (press \key{A} if not) 265\item Press \key{P} and select ``By loose parts'', this should separate the object into its unconnected regions 266\item Export .obj (see above), also check ``Objects as OBJ Objects'' 267\end{enumerate} 268 269\begin{table}[tb] 270\footnotesize 271\begin{tabular}{llll} 272\toprule 273\emph{Parameter} &\emph{Default} &\emph{Range} & \emph{Meaning}\\ 274\midrule 275\parameter{Ka} &set to \parameter{Kd} values & $0\dots1$ each& R/G/B Ambient color\\ 276\parameter{Kd} &0.8 0.8 0.8 & $0\dots1$ each & R/G/B Diffuse color\\ 277\parameter{Ke} &0.0 0.0 0.0 & $0\dots1$ each & R/G/B Emissive color\\ 278\parameter{Ks} &0.0 0.0 0.0 & $0\dots1$ each & R/G/B Specular color\\ 279\parameter{Ns} &8.0 & $0\dots\infty$ & shinyness \\ 280\parameter{d} or \parameter{Tr} &1.0 & $0\dots1$ & opacity \\ 281\parameter{bAlphatest} &0 & 0 or 1 & perform alpha test \\ 282\parameter{bBackface} &0 & 0 or 1 & render backface \\ 283\parameter{map\_Kd} & (none) & filename & texture map to be mixed with Ka, Kd \\ 284\parameter{map\_Ke} & (none) & filename & texture map to be mixed with Ke \\ 285\parameter{map\_bump} & (none) & filename & normal map for surface roughness\\ 286\parameter{illum} & 2 & integer & illumination mode in the standard MTL format. \\ 287\parameter{vis\_fadeIn} & (none) & double & see \ref{sec:scenery3d:Beyond3D}\\ 288\parameter{vis\_fadeOut} & (none) & double & see \ref{sec:scenery3d:Beyond3D}\\ 289\bottomrule 290\end{tabular} 291\caption{MTL parameters evaluated} 292\label{tab:scenery3d:MTL} 293\end{table} 294 295\noindent The MTL file specified by \parameter{mtllib} contains the material parameters. The 296minimum that should be specified is either \parameter{map\_Kd} or a \parameter{Kd} line 297specifying color values used for the respective faces. But there are other 298options in MTL files, and the supported parameters and defaults are listed in 299Table~\ref{tab:scenery3d:MTL}. 300 301If no ambient color is specified, the diffuse color values are taken for the 302ambient color. An optional emissive term \parameter{Ke} can be added, which is 303modulated to only be visible during nighttime. This also requires the 304landscape's self-illumination layer to be enabled. It allows to model 305self-illuminating objects such as street lights, windows etc. It can optionally 306also be modulated by the emissive texture \parameter{map\_Ke}. 307 308If a value for \parameter{Ks} is specified, specularity is evaluated 309using the Phong reflection 310model\footnote{\url{https://en.wikipedia.org/wiki/Phong_reflection_model}} 311with \parameter{Ns} as the exponential shininess constant. Larger 312shininess means smaller specular highlights (more metal-like 313appearance). Specularity is not modulated by the texture 314maps. Unfortunately, some 3D editors export unusable default value 315combinations for \parameter{Ks} and \parameter{Ns}. \program{Blender} 316may create lines with \parameter{Ks}=1/1/1 and \parameter{Ns}=0. This 317creates a look of ``partial overexposed snow fields''. While the 318values are allowed in the specification, in most cases the result 319looks ugly. \emph{Make sure to set \parameter{Ns} to 1 or higher, or 320 disable those two lines.} 321 322If a value for \parameter{d} or \parameter{Tr} exists, alpha blending is enabled for this 323material. This simulates transparency effects. Transparency can be further 324controlled using the alpha channel of the \parameter{map\_Kd} texture. 325 326A simpler and usually more performant way to achieve simple ``cutout'' 327transparency effects is alpha-testing, by setting \parameter{bAlphatest} to 1. This 328simply discards all pixels of the model where the alpha value of the 329\parameter{map\_Kd} is below the \parameter{transparency\_threshold} value from 330\file{scenery3d.ini}, making ``holes'' in the model. This also produces 331better shadows for such objects. If required, alpha testing can be combined with 332``real'' blending-based transparency. 333 334Sometimes, exported objects only have a single side (``paper wall''), and are only visible 335from one side when looked at in Scenery3d. This is caused by an optimization 336called \emph{back-face culling}\footnote{\url{https://en.wikipedia.org/wiki/Back-face_culling}}, 337which skips drawing the back sides of objects because they are usually 338not visible anyway. If possible, avoid such ``thin'' geometry, this will also 339produce better shadows on the object. As a workaround, you can also set 340\parameter{bBackface} to 1 to disable back-face culling for this material. 341 342The optional \parameter{map\_bump} enables the use of a tangent-space 343normal 344maps\footnote{\url{https://en.wikipedia.org/wiki/Normal_mapping}}, 345which provides a dramatic improvement in surface detail under 346illumination. 347 348\subsection{Configuring OBJ for Scenery3d} 349\label{sec:scenery3d:Configuring} 350 351The walkaround in your scene can use a ground level (piece of terrain) 352on which the observer can walk. The observer eye will always stay ``eye 353height'' above ground. Currently, there is no collision detection with 354walls implemented, so you can easily walk through walls, or jump on 355high towers, if their platform or roof is exported in the ground 356layer. If your model has no explicit ground layer, walk will be on the 357highest surface of the scenery layer. If you use the special name 358\parameter{NULL} as ground layer, walk will be above \parameter{zero\_ground\_height} level. 359 360Technically, if your model has cavities or doors, you should export 361your model twice. Once, just the ground plane, i.e. where you will 362walk. Of course, for a temple or other building, this includes its 363socket above soil, and any steps, but pillars should not be included. 364This plane is required to compute 365eye position above ground. Note that it is not possible to walk in 366several floors of a building, or in a multi-plane staircase. You may 367have to export several ``ground'' planes and configure several scenery 368directories for those rare cases. For optimal performance, the ground 369model should consist of as few triangles as you can tolerate. 370 371The second export includes all visible model parts, and will be used for 372rendering. Of course, this requires the ground plane again, but also 373all building elements, walls, roofs, etc. 374 375If you have not done so by yourself, it is recommended to separate 376ground and buildings into Sketchup layers 377(or similar concepts in whichever editor you are using) 378in order to easily switch the model to the right state prior to exporting. 379 380Filename recommendations: 381 382\noindent% 383\begin{tabularx}{\textwidth}{lX} 384\file{<Temple>.skp} &Name of a Sketchup Model file. 385 (The \file{<>} brackets signal ``use your own name here!'') 386 The SKP file is not used by Scenery3d, but you may want 387 to leave it in the folder for later improvements.\\ 388\file{<Temple>.obj} &Model in OBJ format. \\ 389\file{<Temple>\_ground.obj} &Ground layer, if different from Model file. 390\end{tabularx} 391 392\noindent OBJ export may also create folders \file{TX\_<Temple>} and 393\file{TX\_<Temple>\_ground}. You can delete the \file{TX\_<Temple>\_ground} folder, 394\file{<Temple>\_ground.obj} is just used to compute vertical height. 395 396%Stellarium uses a directory to store additional data per-user. On Windows, this 397%defaults to \verb|C:\Documents and Settings\<username>\Application Data\Stellarium|, 398%but you can use another directory by using the command-line 399%argument \parameter{--user-dir <USERDATA>}. We will refer to this directory. 400 401Put the 402OBJ, MTL and TX directories into a subdirectory of your user directory (see section~\ref{sec:Directories}), e.g.\ 403\file{<USERDATA>/Stellarium/scenery3d/<Temple>}, and add a text file into it 404called \file{scenery3d.ini} (This name is mandatory!) with content described as 405follows. 406 407% A Sketchup plugin "Write scenery3d.ini for Stellarium" will write this 408% file. Locate the directory where the .obj file(s) reside(s), and store 409% scenery3d.ini there. If you have other modelers and models, or if your 410% model is not georeferenced in Sketchup, write the file yourself and 411% use the following format. 412% 413% TBD GZ: Release this Sketchup export plugin? 414 415\noindent% 416\begin{tabularx}{\textwidth}{lX} 417\texttt{[model]}&\\ 418\texttt{name=<Temple>}& Unique ID within all models in scenery3d directory. 419 Recommendation: use directory name.\\ 420\texttt{landscape=<landscapename>}& Name of an available Stellarium landscape. 421\end{tabularx} 422 423\noindent This is required if the landscape file includes geographical 424coordinates and your model does not: First, the location coordinates 425of the \file{landscape.ini} file are used, then location coordinates given here. 426The landscape also provides the background image of your scenery. If 427you want a zero-height (mathematical) horizon, use the provided 428landscape called \file{Zero Horizon}. 429 430\noindent% 431\begin{tabularx}{\textwidth}{lX} 432\texttt{scenery=<Temple>.obj} &The complete model, including visible ground.\\ 433\texttt{ground=<Temple>\_ground.obj} &Optional: separate ground plane. (NULL for zero altitude.)\\ 434\texttt{description=<Description>} &A basic scene description (including HTML tags) 435\end{tabularx} 436 437\noindent The \file{scenery3d.ini} may contain a simple scene description, but it is 438recommended to use the \emph{localizable} description format: in the scene's 439directory (which contains \file{scenery3d.ini}) create files in the format 440\file{description.<lang>.utf8} which can contain arbitrary 441UTF-8--encoded HTML content. \parameter{<lang>} stands for the ISO~639 442language code. 443 444\noindent% 445\begin{longtable}{lp{92mm}} 446\multicolumn{2}{l}{\texttt{author=<Your Name yourname@yourplace.com>}}\\ 447\multicolumn{2}{l}{\texttt{copyright=<Copyright Info>}}\\ 448\texttt{obj\_order=XYZ} & Use this if you have used an exporter which swaps Y/Z coordinates. 449 Defaults to \texttt{XYZ}, other options: \texttt{XZY}, \texttt{YZX}, \texttt{YXZ}, \texttt{ZXY}, \texttt{ZYX}\\ 450\texttt{camNearZ=0.3} & This defines the distance of the camera near plane, default 0.3. 451 Everything closer than this value to the camera can not be 452 displayed. Must be larger than zero. It may seem tempting 453 to set this very small, but this will lead to accuracy issues. 454 Recommendation is not to go under 0.1\\ 455\texttt{camFarZ=10000} & Defines the maximal viewing distance, default 10000.\\ 456\texttt{shadowDistance=<val>}& The maximal distance shadows are displayed. If left out, the 457 value from \texttt{camFarZ} is used here. If this is set to a smaller 458 value, this may increase the quality of the shadows that are 459 still visible.\\ 460\texttt{shadowSplitWeight=0..1}& Decimal value for further shadow tweaking. If you require 461 better shadows up close, try setting this to higher values. 462 The default is calculated using a heuristic that incorporates 463 scene size.\\ 464\texttt{[general]}&\\ 465\end{longtable} 466 467\noindent The general section defines some further import/rendering options. 468% GZ TBD: Why do we need ground normals? 469 470 471\noindent% 472\begin{tabularx}{\textwidth}{lX} 473\texttt{transparency\_threshold=0.5} &Defines the alpha threshold for alpha-testing, as described in section~\ref{sec:scenery3d:OBJlimitations}. Default \texttt{0.5}\\ 474\texttt{scenery\_generate\_normals=0} &Boolean, if true normals are recalculated by the plugin, instead of imported. Default \texttt{false}\\ 475\texttt{ground\_generate\_normals=0} &Boolean, same as above, for ground model. Default \texttt{false}.\\ 476\texttt{[location]} & 477\end{tabularx} 478 479\noindent Optional section to specify geographic longitude $\lambda$, latitude $\varphi$, 480and altitude. The section is required if \verb|coord/convergence_angle=from_grid|, else 481location is inherited from landscape. 482 483\noindent% 484\begin{tabularx}{\textwidth}{lX} 485\multicolumn{2}{l}{\texttt{planet = Earth}}\\ 486\texttt{latitude = +48d31'30.4"} & Required if \texttt{coord/convergence\_angle=from\_grid}\\ 487\texttt{longitude = +16d12'25.5"} & "--"\\ 488\texttt{altitude =from\_model|<int>} & altitude (for astronomical computations) can be computed from the model: if 489 \texttt{from\_model}, it is computed as $(z_{min}+z_{max})/2+\mathtt{orig\_H}$, 490 i.e.\ from the model bounding box centre height.\\ 491\multicolumn{2}{l}{\texttt{display\_fog = 0}}\\ 492\multicolumn{2}{l}{\texttt{atmospheric\_extinction\_coefficient = 0.2}}\\ 493\multicolumn{2}{l}{\texttt{atmospheric\_temperature = 10.0}}\\ 494\multicolumn{2}{l}{\texttt{atmospheric\_pressure = -1}}\\ 495\multicolumn{2}{l}{\texttt{light\_pollution = 1}}\\ 496\multicolumn{2}{l}{\texttt{[coord]}}\\ 497\end{tabularx} 498 499\noindent Entries in the \verb|[coord]| section are again optional, 500default to zero when not specified, but are required if you want to 501display meaningful eye coordinates in your survey (world) coordinate 502system, like UTM or Gauss-Kr\"uger. 503 504\begin{longtable}{lp{84mm}} 505\texttt{grid\_name=<string> }& Name of grid coordinates, e.g. \texttt{"UTM 33 U (WGS 84)"}, 506 \texttt{"Gauss-Kr\"uger M34"} or \texttt{"Relative to <Center>"} This name is 507 only displayed, there is no evaluation of its contents.\\ 508\texttt{orig\_E=<double> | (Easting)} &East-West-distance to zone central meridian\\ 509\texttt{orig\_N=<double> | (Northing)} &North distance from Equator\\ 510\texttt{orig\_H=<double> | (Height)} &Altitude above Mean Sea Level of model origin\\ 511\end{longtable} 512 513\noindent These entries describe the offset, in metres, of the model coordinates relative 514to coordinates in a geographic grid, like Gauss-Kr\"uger or UTM. If you have your model 515vertices specified in grid coordinates, do not specify \verb|orig_...| data, but 516please definitely add \verb|start_...| data, below. 517 518Note that using grid coordinates without offset for the vertices is 519usually a bad idea for real-world applications like surveyed sites in 520UTM coordinates. Coordinate values are often very large numbers 521(ranging into millions of meters from equator and many thousands from 522the zone meridian). If you want to assign millimetre values to model 523vertices, you will hit numerical problems with the usual 524single-precision floating point arithmetic. Therefore we can specify 525this offset which is only necessary for coordinate display. 526 527Typically, digital elevation models and building structures built on 528those are survey-grid aligned, so true geographical north for a place 529with geographical longitude $\lambda$ and latitude $\varphi$ will in 530general not coincide with grid north, the difference is known as 531\indexterm{meridian convergence}\footnote{% 532 \url{https://en.wikipedia.org/wiki/Transverse_Mercator_projection}}. 533\begin{equation} 534\gamma(\lambda, \varphi)=\arctan(\tan(\lambda-\lambda_0)\sin\varphi) 535\end{equation} 536This amount can be given in \verb|convergence_angle| (degrees), so 537that your model will be rotated clockwise by this amount around the 538vertical axis to be aligned with True North\footnote{Note that 539 Sketchup's \emph{georeferencing dictionary} provides a NorthAngle 540 entry, which is $360-\mathtt{convergence\_angle}$.}. 541 542\begin{configfile} 543convergence_angle=from_grid|<double> 544grid_meridian=<double>|+<int>d<int>'<float>" 545\end{configfile} 546 547\noindent \texttt{grid\_meridian} is the central meridian $\lambda_0$ of grid 548zone, e.g.\ for UTM or Gauss-Kr\"uger, and is only required to compute 549convergence angle if \texttt{convergence\_angle=from\_grid}. 550 551 552 553\begin{configfile} 554zero_ground_height=<double> 555\end{configfile} 556height of terrain outside \file{<Temple>\_ground.OBJ}, or if \verb|ground=NULL|. 557Allows smooth approach from outside. This value is relative to the model 558origin, or typically close to zero, i.e., use a Z value in model coordinates, 559not world coordinates! (If you want the terrain height surrounding your model to 560be \texttt{orig\_H}, use 0, not the correct mean height above sea level!) Defaults 561to minimum of height of ground level (or model, resp.) bounding box. 562 563\begin{tabularx}{\textwidth}{lX} 564\multicolumn{2}{l}{\texttt{start\_E=<double>}}\\ 565\multicolumn{2}{l}{\texttt{start\_N=<double>}} \\ 566\texttt{start\_H=<double>} &only meaningful if \texttt{ground==NULL}, else \texttt{H} is derived from ground \\ 567\texttt{start\_Eye=<double>} &default: \texttt{1.65m} \\ 568\multicolumn{2}{l}{\texttt{start\_az\_alt\_fov=<az\_deg>,<alt\_deg>,<fov\_deg>}}\\ 569\ &initial view direction and field of view.\\ 570\end{tabularx} 571 572\noindent \texttt{start\_...} defines the view position to be set after loading the scenery. 573Defaults to center of model boundingbox. 574 575It is advisable to use the grid coordinates of the location of the panoramic 576photo (landscape) as \texttt{start\_...} coordinates, or the correct coordinates 577and some carefully selected \texttt{start\_az\_alt\_fov} in case of certain view 578corridors (temple axes, \ldots). 579 580\subsection{Concatenating OBJ files} 581\label{sec:scenery3d:concatenating} 582 583Some automated workflows may involve tiled landscape areas, e.g. to 584overcome texture limitations or triangle count limits in simpler tools 585like \program{Sketchup}. In this case you can create separate meshes 586in the same coordinate system, but you need to concatenate them. One 587powerful program to assemble your parts is again \program{Blender}. 588 589In \program{Blender}, import the OBJ files \menu{File>Import>Wavefront 590 .obj}. If your OBJ coordinates have Z as vertical axis (common for 591terrestrial models), use ``Z up'', ``-Y Forward'' as import settings 592for the coordinate axes. The model will appear south-up. 593 594Blender may not show anything except the default cube because of 595aggressive camera far plane clipping. Press \keys{N} and in the 596\menu{View} set at least the far clipping plane as required to see the full 597extent of your terrain model. Then press \menu{View>View All} (or \keys{Home}). 598 599 600 601The landscape may look white now. Switch on textured view if required 602(\keys{\Alt+Z}). If the scene looks almost black now, reconfigure the 603light to be sunlight: Select the lamp in the outliner graph, press the 604lamp icon and in the \menu{Lamp} select ``Sun''. Now the scene should 605be in full color, and the Y axis should point towards grid-south. 606 607After importing the first model, you may consider locking it in place 608to avoid errors. Select the model in the outliner, select the cube 609button below, then open \menu{Transform Locks} and lock all. The other 610model parts may have to be transformed, and numerical transformation 611can be added in the \menu{Transform} settings in this menu. 612 613If you have created a VRML (WRL) of some structures in \program{ArcScene}, 614export that without shifting to center, and import the WRL file in 615\program{Blender} with default orientation ``Y up'', ``Z 616forward''. Models from other sources may still be different. 617 618In the end, all parts should fit neatly together. \program{Blender} is 619a very powerful program, you can enhance your model as you wish. 620 621When the model configuration is complete, select all relevant parts 622which you want to have visible in Stellarium (click on the lines in 623the outline view containing the object names to light them up gray, 624then Rightclick-Select, so that the triangle (mesh) icon has a colored 625background circle) and press \key{\ctrl+J} to optionally join them, 626then export to a single OBJ \menu{File>Export>Wavefront .obj}. In the 627export options, apply ``Selection Only'', and ``-Y Forward'' and ``Z 628Up''% 629\footnote{https://blender.stackexchange.com/questions/3352/merging-multiple-obj-files}. 630 631Verify the new model loads correctly, e.g.\ in \program{Meshlab}\footnote{\url{https://www.meshlab.net/}}! 632 633\subsection{Beyond 3D: Temporally evolving Models} 634\label{sec:scenery3d:Beyond3D} 635 636Stellarium \newFeature{0.16.1} working as ``time machine'' can display the sky for any calendar date in its range of valid dates. 637Also landscapes and human-built structures evolve. Temples are being rebuilt, changed, re-dedicated or repurposed, 638new windows are cut, old windows closed. 639To show landscape and buildings in the right shape for the time in question, we can make material transparent, 640so that parts of the model are not displayed. To allow for archaeological uncertainties in dating 641construction and destruction, we can gradually fade in and fade out the model parts in question \citep{Zotti:SEAC2017}. 642 643To enable this magic, you must combine all your models into one (see section~\ref{sec:scenery3d:concatenating}), 644export as one OBJ/MTL as usual, and manually edit the MTL file. It is wise to give the material 645for the parts in question a reasonable name that you can later identify in the MTL file. 646Then you simply add one or both of the new keywords \texttt{vis\_fadeIn} or \texttt{vis\_fadeOut} 647to the material description, with 2 arguments which are the Julian days of begin and end of a phase transition. 648For sharp transitions, just use the same JD dates. 649 650\begin{configfile} 651# Some structure has been put up around -3100/-3000 652vis_fadeIn 588783.5 625308.5 653# Fade away between 500AD/700AD 654vis_fadeOut 1903682.5 1976732.5 655\end{configfile} 656 657 658\subsection{Working with non-georeferenced OBJ files} 659\label{sec:scenery3d:NonGeoreferenced} 660 661 662There exists modeling software which produces nice models, but without 663concept of georeference. One spectacular example is \program{AutoDesk PhotoFly}, 664a cloud application which delivers 3D models from a bunch of photos 665uploaded via its program interface. This ``technological preview'' is 666in version 2 and free of cost as of mid-2011. 667 668The problem with these models is that you cannot assign surveyed 669coordinates to points in the model, so either you can georeference the 670models in other applications, or you must find the correct 671transformation matrix. Importing the OBJ in \program{Sketchup} may take a long 672time for detailed photo-generated models, and the texturing may 673suffer, so you can cut the model down to the minimum necessary e.g.\ in 674\program{Meshlab}, and import just a stub required to georeference the model in 675\program{Sketchup}. 676 677Now, how would you find the proper orientation? The easiest chance 678would be with a structure visible in the photo layer of \program{Google 679Earth}. So, start a new model and immediately \menu{add location} from the 680\program{Google Earth} interface. Then you can import the OBJ with TIG's importer 681plugin. If the imported model looks perfect, you may just place the 682model into the \program{Sketchup} landscape and export a complete landscape just 683like above. If not, or if you had to cut/simplify the OBJ to be able 684to import it, you can rotate/scale the OBJ (it must be grouped!). If 685you see a shadow in the photos, you may want to set the date/time of 686the original photos in the scene and verify that the shadows created by 687\program{Sketchup} illuminating the model match those in the model's photo 688texture. When you are satisfied with placement/orientation, you create 689a \file{scenery3d.ini} like above with the command 690\menu{Plugins>ASTROSIM/Stellarium scenery3d helpers>Create scenery3d.ini}. 691 692Then, you select the OBJ group, open the \menu{Windows>Ruby Console} and readout data by calling 693\menu{Plugins>ASTROSIM/Stellarium scenery3d helpers>Export transformation 694of selected group}. 695 696On the Ruby console, you will find a line of numbers (the $4\times4$ 697transformation matrix) which you copy/paste (all in one line!) into the 698\file{[model]} section in \file{scenery3d.ini}. 699\begin{configfile} 700obj2grid_trafo=<a11>,<a12>,<a13>,<a14>,<a21>,<a22>,<a23>,<a24>, 701 <a31>,<a32>,<a33>,<a34>,<a41>,<a42>,<a43>,<a44> 702\end{configfile} 703You edit the \file{scenery3d.ini} to use your full (unmodified) 704\program{PhotoFly} model and, if you don't have a panorama, take \parameter{Zero Horizon} 705landscape as (no-)background. It depends on the model if you want to 706be able to step on it, or to declare \texttt{ground=NULL} for a 707constant-height ground. Run Stellarum once and adjust the 708\texttt{start\_N}, \texttt{start\_E} and \texttt{zero\_ground\_height}. 709 710\subsection{Rotating OBJs with recognized survey points} 711\label{sec:scenery3d:RotatingOBJ} 712 713If you have survey points measured in a survey grid plus an image-based model 714with those points visible, you can use Meshlab to find the model 715vertex coordinates in the photo model, and some other program like 716\program{CoordTrans} in the \program{JavaGraticule3D} suite to find either the matrix 717values to enter in \file{scenery3d.ini} or even rotate the OBJ 718points. However, this involves more math than can be described here; 719if you came that far, you likely know the required steps. Here it 720really helps if you know how to operate automatic text processors like 721\program{AWK}. 722 723\section{Predefined views} 724You can also configure and distribute some predefined views with your 725model in a \file{viewpoints.ini} file. The viewpoints can be loaded 726and stored with the viewpoint dialog which you can call with the 727\guibutton{0.6}{bt_scenery3d_eyepoint_off.png} button. See the provided 728``Sterngarten'' scene for an example. These entries are not editable 729by the user through the interface. The user can always save his own 730views, they will be saved into the file \file{userviews.ini} in the 731user's Stellarium user directory, and are editable. 732 733\begin{configfileScr} 734[StoredViews] 735size=<int> Defines how many entries are in this file. 736 Prefix each entry with its index! 7371/label=<string> The name of this entry 7381/description=<string> A description of this entry (can include HTML) 7391/position=<x,y,z,h> The x,y,z grid coordinates 740 (like orig_* or start_* in scenery3d.ini) 741 + the current eye height h 7421/view_fov=<az_deg,alt_deg,fov_deg> The view direction + FOV 743 (like start_az_alt_fov in scenery3d.ini) 744; an example for a second entry (note the 2 at the beginning of each line!) 7452/label = Signs 7462/description = Two signs that describe the Sterngarten 7472/position = 593155.2421,5333348.6304,325.7295809038,0.8805 7482/view_fov = 84.315399,-8.187078,83.000000 749\end{configfileScr} 750 751\section{Example} 752\label{sec:scenery3d:example} 753Let us add a quick example here. A recent paper~\citep{Pollard:2017:UffingtonHorse} claims that the Uffington White Horse, 754a geoglyph carved into a hillsite in England during the Bronze Age, may depict the mythical ``Sun Horse'', a common conception of that period. 755 756Unfortunately, as of 2017, the official UK Lidar repository does not include the Uffington area, 757so a detailed GIS-based model is not available. We could use EUdem25 data with aerial imagery, 758or for a quick look, we just use \program{Sketchup}. 759Yet another unfortunate development: Trimble declared that after the 5-year transition 760period from Google to Trimble is over in May 2017, terrain modelling will be limited to \program{Sketchup Pro}. 761But note that a fresh installation comes with a 30-day Pro trial time, this should be enough for this example. 762 763First, locate the site in \program{Google Earth} at $\lambda=-1.56718, \varphi=51.582843$. (Or just search for ``Uffington''.) 764Try to identify which parts of the landscape may be visible from your site, so you can estimate which parts of terrain should be included in the model. 765Open \program{Sketchup}, select the meter-based ``Landscape Architecture'' template, add \menu{View>Toolbars\ldots}: Locations. 766Click on the ``Add Location'' button of that toolbar. Enter ``Uffington'' into the location search dialog. 767This brings you close to our site of interest. Clip a part of terrain to import it to Sketchup. Optionally, add more terrain. 768 769If installed, TIG's OBJ exporter is available from the \menu{File} menu, or you can use \program{Sketchup Pro}'s built-in OBJ export. 770Export \file{UffingtonHorse.obj} to a subdirectory \file{scenery3d/Uffington} in your Stellarium user data directory. 771The geolocation is stored in an ``AttributeDictionary''. To read this, press \menu{Window>Ruby Console} to open the Ruby Console. 772Then write a few lines of Ruby to get access to the \texttt{Georeference} dictionary and other data: 773\begin{commands} 774model=Sketchup.active_model 775attrdicts=model.attribute_dictionaries 776attrdicts.each {|d| 777 puts "AttributeDictionary: %s" % d.name 778 d.each_pair { |k, v| puts " %s=%s" % [k, v] } 779} 780model.shadow_info.each{|k,v| puts " #{k} #{v}"} 781utm=model.point_to_utm Geom::Point3d.new(0,0,0) 782puts("grid_name=UTM %i %s (%s)" % 783 [ utm.zone_number, utm.zone_letter, model.get_datum]) 784\end{commands} 785 786 787Note the \texttt{ModelTranslation} values. Those are inches (of all units!) in the UTM reference frame 788and define the model coordinate origin in world coordinates. (Actually, it uses the negative values.) 789Multiplication by 2.54 gives cm, and by 0.0254, meters in the UTM coordinate system. 790We will use the negatives of these values as \texttt{orig\_E}, \texttt{orig\_N}, \texttt{orig\_H}. 791Additionally, we have found information about meridian convergence correction (\program{Sketchup}'s \texttt{NorthAngle}), 792UTM zone number etc. All this goes into our configuration file. 793Create this file \file{scenery3d.ini} with the content seen in fig.~\ref{fig:scenery3d:UffingtonIni} 794\begin{figure}[p] 795\begin{configfile} 796[model] 797name=UffingtonHorse 798;Either a fitting landscape or just 'Zero Horizon': 799landscape=Zero Horizon 800scenery=UffingtonHorse.obj 801;activate the next line if you have a separate ground layer 802;ground=UffingtonHorse_ground.obj 803;If model Y-axis points up, activate the next line 804;obj_order=XZY 805author=Georg Zotti 806copyright=(c) 2017 Georg Zotti 807description=Uffington Horse may represent the Sun Horse. \ 808 See Joshua Pollard in Antiquity 91 356(2017): 406-20. 809[location] 810name=UffingtonHorse 811country=UK 812planetName=Earth 813;Set the following to a fitting landscape 814landscapeKey=Zero Horizon 815longitude=-1.56718254089355 816latitude=51.5828432749823 817altitude=137 818[coord] 819grid_name=UTM 30 U (WGS 84) 820gridType=UTM 821orig_E=599273.02119578 822orig_N=5715615.15079106 823orig_H=136.295297626736 824convergence_angle=1.12284363771988 825;Height used outside the terrain, to not "fall off" the rim. 826zero_ground_height=137 827;You may want to reset these coordinates. 828;Observer is set to those on loading the scenery. 829start_E=599273.02119578 830start_N=5715615.15079106 831start_az_alt_fov=50,10,83 832\end{configfile} 833\caption{\file{scenery3d.ini} for the Uffington example.} 834\label{fig:scenery3d:UffingtonIni} 835\end{figure} 836 837\section{Limitations} 838\label{sec:scenery3d:Limitations} 839 840Models with up to 14 million triangles have been used successfully on 841a mid-range notebook PC from 2016. However, take some restrictions 842into account: 843 844\begin{itemize} 845\item The model is rendered in Cartesian coordinates. Earth's surface 846 is curved. If your model extends by tens of kilometres, the visible 847 horizon formed by faraway mountains may appear too high. You can 848 \newFeature{0.20.2} display a landscape polygon defined in the 849 currently displayed Landscape on top of your 3D scene by activating 850 \menu{Draw horizon polyline in foreground} in the plugin's 851 settings dialog. 852\item 853 The OBJ format is static. Simulation of interaction with 3D objects 854 is not possible with this plugin. 855\end{itemize} 856 857\section*{Authors and Acknowledgements} 858\label{sec:scenery3d:Acknowledgments} 859 860 861Scenery3d was conceived by Georg Zotti for the 862ASTROSIM\footnote{\url{https://astrosim.univie.ac.at}} project. A first 863prototype was implemented in 2010/2011 by Simon Parzer and 864Peter Neubauer as student work supervised by Michael Wimmer (TU Wien). 865Models for accuracy tests (Sterngarten, Testscene), and later 866improvements in integration, user interaction, \file{.ini} option handling, 867OBJ/MTL loader bugfixes and georeference testing by Georg Zotti. 868 869Andrei Borza in 2011/12 further improved rendering quality (shadow 870mapping, normal mapping) and 871speed~\citep{Zotti-Neubauer:VSMM2012,Zotti-Neubauer:EuroMed2012,Zotti:2012:SpringerAA}. 872 873In 2014--17, 874Florian Schaukowitsch adapted the code to work with Qt~5 and the 875Stellarium~0.13 codebase, replaced the renderer with a more efficient, fully 876shader-based system, implemented various performance, quality and usability 877enhancements, and did some code cleanup. Both Andrei and Florian were again 878supervised by Michael Wimmer~\citep{Zotti:CHNT2015,Zotti:SEAC2015,Zotti:SEAC2017}. 879 880This work has been originally created during the ASTROSIM project supported 2008-2012 by 881the Austrian Science Fund (FWF) under grant number P~21208-G19. Further development is 882partially supported by the Ludwig Boltzmann Institute for Archaeological Prospection and Virtual Archaeology in Vienna, Austria\footnote{% 883 \url{https://archpro.lbg.ac.at}}. 884 885If you are using this plugin in scientific work, please cite: \citep{Zotti:CHNT2015,Zotti:SEAC2015,Zotti:SEAC2017,Zotti-etal:SIA2016,Zotti:TAG2016,Zotti-etal:JSA2020.6.2}. 886 887 888%%% Local Variables: 889%%% mode: latex 890%%% TeX-master: "guide" 891%%% End: 892 893