diff --git a/docs/source/_static/CursorInfo.png b/docs/source/_static/CursorInfo.png deleted file mode 100644 index 7ce5165..0000000 Binary files a/docs/source/_static/CursorInfo.png and /dev/null differ diff --git a/docs/source/_static/Desktop1.png b/docs/source/_static/Desktop1.png deleted file mode 100644 index 7d4c0f8..0000000 Binary files a/docs/source/_static/Desktop1.png and /dev/null differ diff --git a/docs/source/_static/ColorMenu.png b/docs/source/_static/GUI/ColorMenu.png similarity index 100% rename from docs/source/_static/ColorMenu.png rename to docs/source/_static/GUI/ColorMenu.png diff --git a/docs/source/_static/GUI/CursorInfo.png b/docs/source/_static/GUI/CursorInfo.png new file mode 100644 index 0000000..d29c4d5 Binary files /dev/null and b/docs/source/_static/GUI/CursorInfo.png differ diff --git a/docs/source/_static/GUI/Desktop1.png b/docs/source/_static/GUI/Desktop1.png new file mode 100644 index 0000000..79995d9 Binary files /dev/null and b/docs/source/_static/GUI/Desktop1.png differ diff --git a/docs/source/_static/Desktop2.png b/docs/source/_static/GUI/Desktop2.png similarity index 100% rename from docs/source/_static/Desktop2.png rename to docs/source/_static/GUI/Desktop2.png diff --git a/docs/source/_static/Desktop3.png b/docs/source/_static/GUI/Desktop3.png similarity index 100% rename from docs/source/_static/Desktop3.png rename to docs/source/_static/GUI/Desktop3.png diff --git a/docs/source/_static/Desktop4.png b/docs/source/_static/GUI/Desktop4.png similarity index 100% rename from docs/source/_static/Desktop4.png rename to docs/source/_static/GUI/Desktop4.png diff --git a/docs/source/_static/Desktop5.png b/docs/source/_static/GUI/Desktop5.png similarity index 100% rename from docs/source/_static/Desktop5.png rename to docs/source/_static/GUI/Desktop5.png diff --git a/docs/source/_static/Keypad.png b/docs/source/_static/GUI/Keypad.png similarity index 100% rename from docs/source/_static/Keypad.png rename to docs/source/_static/GUI/Keypad.png diff --git a/docs/source/_static/PaintMenu.png b/docs/source/_static/GUI/PaintMenu.png similarity index 100% rename from docs/source/_static/PaintMenu.png rename to docs/source/_static/GUI/PaintMenu.png diff --git a/docs/source/_static/PlotsMenu.png b/docs/source/_static/GUI/PlotsMenu.png similarity index 100% rename from docs/source/_static/PlotsMenu.png rename to docs/source/_static/GUI/PlotsMenu.png diff --git a/docs/source/_static/GUI/QuickMenu.png b/docs/source/_static/GUI/QuickMenu.png new file mode 100644 index 0000000..9d21916 Binary files /dev/null and b/docs/source/_static/GUI/QuickMenu.png differ diff --git a/docs/source/_static/SettingsMenu.png b/docs/source/_static/GUI/SettingsMenu.png similarity index 100% rename from docs/source/_static/SettingsMenu.png rename to docs/source/_static/GUI/SettingsMenu.png diff --git a/docs/source/_static/SourceInfo.png b/docs/source/_static/GUI/SourceInfo.png similarity index 100% rename from docs/source/_static/SourceInfo.png rename to docs/source/_static/GUI/SourceInfo.png diff --git a/docs/source/_static/SourcesMenu.png b/docs/source/_static/GUI/SourcesMenu.png similarity index 100% rename from docs/source/_static/SourcesMenu.png rename to docs/source/_static/GUI/SourcesMenu.png diff --git a/docs/source/_static/VR-first-view.png b/docs/source/_static/GUI/VR-first-view.png similarity index 100% rename from docs/source/_static/VR-first-view.png rename to docs/source/_static/GUI/VR-first-view.png diff --git a/docs/source/_static/GUI/VideoMakerModeMenu_UI.png b/docs/source/_static/GUI/VideoMakerModeMenu_UI.png new file mode 100644 index 0000000..8418c36 Binary files /dev/null and b/docs/source/_static/GUI/VideoMakerModeMenu_UI.png differ diff --git a/docs/source/_static/GUI/VideoMakerPointList_UI.png b/docs/source/_static/GUI/VideoMakerPointList_UI.png new file mode 100644 index 0000000..942cf14 Binary files /dev/null and b/docs/source/_static/GUI/VideoMakerPointList_UI.png differ diff --git a/docs/source/_static/GUI/VideoMaker_RENDER_File_FFmpeg_blurred.png b/docs/source/_static/GUI/VideoMaker_RENDER_File_FFmpeg_blurred.png new file mode 100644 index 0000000..7bca647 Binary files /dev/null and b/docs/source/_static/GUI/VideoMaker_RENDER_File_FFmpeg_blurred.png differ diff --git a/docs/source/_static/GUI/VideoMaker_RENDER_IDVS_annotated.png b/docs/source/_static/GUI/VideoMaker_RENDER_IDVS_annotated.png new file mode 100644 index 0000000..3a334b1 Binary files /dev/null and b/docs/source/_static/GUI/VideoMaker_RENDER_IDVS_annotated.png differ diff --git a/docs/source/_static/GUI/VideoMaker_RENDER_playing_annotated.png b/docs/source/_static/GUI/VideoMaker_RENDER_playing_annotated.png new file mode 100644 index 0000000..ba51e8c Binary files /dev/null and b/docs/source/_static/GUI/VideoMaker_RENDER_playing_annotated.png differ diff --git a/docs/source/_static/VoiceCommandMenu.png b/docs/source/_static/GUI/VoiceCommandMenu.png similarity index 100% rename from docs/source/_static/VoiceCommandMenu.png rename to docs/source/_static/GUI/VoiceCommandMenu.png diff --git a/docs/source/_static/QuickMenu.png b/docs/source/_static/QuickMenu.png deleted file mode 100644 index 1d63ea3..0000000 Binary files a/docs/source/_static/QuickMenu.png and /dev/null differ diff --git a/docs/source/_static/desktop_selection_tool/1_desktop_selection_tool.jpg b/docs/source/_static/desktop_selection_tool/1_desktop_selection_tool.jpg new file mode 100644 index 0000000..c3762b7 Binary files /dev/null and b/docs/source/_static/desktop_selection_tool/1_desktop_selection_tool.jpg differ diff --git a/docs/source/_static/desktop_selection_tool/2_desktop_selection_tool.jpg b/docs/source/_static/desktop_selection_tool/2_desktop_selection_tool.jpg new file mode 100644 index 0000000..a0552f1 Binary files /dev/null and b/docs/source/_static/desktop_selection_tool/2_desktop_selection_tool.jpg differ diff --git a/docs/source/_static/desktop_selection_tool/3_desktop_selection_tool.jpg b/docs/source/_static/desktop_selection_tool/3_desktop_selection_tool.jpg new file mode 100644 index 0000000..194da07 Binary files /dev/null and b/docs/source/_static/desktop_selection_tool/3_desktop_selection_tool.jpg differ diff --git a/docs/source/_static/desktop_selection_tool/4_desktop_selection_tool.jpg b/docs/source/_static/desktop_selection_tool/4_desktop_selection_tool.jpg new file mode 100644 index 0000000..858639d Binary files /dev/null and b/docs/source/_static/desktop_selection_tool/4_desktop_selection_tool.jpg differ diff --git a/docs/source/_static/desktop_selection_tool/5_desktop_selection_tool.jpg b/docs/source/_static/desktop_selection_tool/5_desktop_selection_tool.jpg new file mode 100644 index 0000000..574da93 Binary files /dev/null and b/docs/source/_static/desktop_selection_tool/5_desktop_selection_tool.jpg differ diff --git a/docs/source/_static/desktop_selection_tool/6_desktop_selection_tool.jpg b/docs/source/_static/desktop_selection_tool/6_desktop_selection_tool.jpg new file mode 100644 index 0000000..af74f6e Binary files /dev/null and b/docs/source/_static/desktop_selection_tool/6_desktop_selection_tool.jpg differ diff --git a/docs/source/_static/desktop_selection_tool/7_desktop_selection_tool.jpg b/docs/source/_static/desktop_selection_tool/7_desktop_selection_tool.jpg new file mode 100644 index 0000000..7ea91dc Binary files /dev/null and b/docs/source/_static/desktop_selection_tool/7_desktop_selection_tool.jpg differ diff --git a/docs/source/_static/shape_selection_tool/1_shape_selection.png b/docs/source/_static/shape_selection_tool/1_shape_selection.png new file mode 100644 index 0000000..0165a5b Binary files /dev/null and b/docs/source/_static/shape_selection_tool/1_shape_selection.png differ diff --git a/docs/source/_static/shape_selection_tool/2_shape_selection_tool.png b/docs/source/_static/shape_selection_tool/2_shape_selection_tool.png new file mode 100644 index 0000000..c57f910 Binary files /dev/null and b/docs/source/_static/shape_selection_tool/2_shape_selection_tool.png differ diff --git a/docs/source/_static/shape_selection_tool/3_shape_selection_tool.png b/docs/source/_static/shape_selection_tool/3_shape_selection_tool.png new file mode 100644 index 0000000..65bcb68 Binary files /dev/null and b/docs/source/_static/shape_selection_tool/3_shape_selection_tool.png differ diff --git a/docs/source/_static/shape_selection_tool/4_shape_selection_tool.png b/docs/source/_static/shape_selection_tool/4_shape_selection_tool.png new file mode 100644 index 0000000..552d14e Binary files /dev/null and b/docs/source/_static/shape_selection_tool/4_shape_selection_tool.png differ diff --git a/docs/source/_static/shape_selection_tool/5_shape_selection_tool.jpg b/docs/source/_static/shape_selection_tool/5_shape_selection_tool.jpg new file mode 100644 index 0000000..f66917e Binary files /dev/null and b/docs/source/_static/shape_selection_tool/5_shape_selection_tool.jpg differ diff --git a/docs/source/_static/shape_selection_tool/6_shape_selection_tool.jpg b/docs/source/_static/shape_selection_tool/6_shape_selection_tool.jpg new file mode 100644 index 0000000..6f4ef7a Binary files /dev/null and b/docs/source/_static/shape_selection_tool/6_shape_selection_tool.jpg differ diff --git a/docs/source/_static/shape_selection_tool/7_shape_selection_tool.jpg b/docs/source/_static/shape_selection_tool/7_shape_selection_tool.jpg new file mode 100644 index 0000000..b90cb22 Binary files /dev/null and b/docs/source/_static/shape_selection_tool/7_shape_selection_tool.jpg differ diff --git a/docs/source/_static/shape_selection_tool/8_shape_selection_tool.jpg b/docs/source/_static/shape_selection_tool/8_shape_selection_tool.jpg new file mode 100644 index 0000000..1dd3bbb Binary files /dev/null and b/docs/source/_static/shape_selection_tool/8_shape_selection_tool.jpg differ diff --git a/docs/source/_static/shape_selection_tool/9_shape_selection_tool.jpg b/docs/source/_static/shape_selection_tool/9_shape_selection_tool.jpg new file mode 100644 index 0000000..79b97d3 Binary files /dev/null and b/docs/source/_static/shape_selection_tool/9_shape_selection_tool.jpg differ diff --git a/docs/source/about.rst b/docs/source/about.rst index 320fde3..7dc43be 100644 --- a/docs/source/about.rst +++ b/docs/source/about.rst @@ -2,7 +2,7 @@ About iDaVIE ============ -iDaVIE (the immersive Data Visualisation Interactive Explorer) was conceived by and is being developed under the custody of the IDIA Visualisation Laboratory. It provides a Virtual Reality experience for data cube exploration. It visualises 3D data in an interaction 'box', a 3D block (or elongated cube) in VR space which allows the user to extract vital feedback information about the enclosed data (including cumulative statistics and historical data). +iDaVIE (the immersive Data Visualisation Interactive Explorer) was conceived by and is being developed under the custody of the IDIA Visualisation Laboratory. It provides a Virtual Reality experience for data cube exploration. It visualises 3D data in an interaction 'box', a 3D block (or elongated cube) in VR space which allows the user to extract vital feedback information about the enclosed data (including cumulative statistics and historical data). You can `send us an email `_ if you want to be added to the iDaVIE mailing list to receive news about updates and new features to iDaVIE. Contributors ------------ diff --git a/docs/source/build.rst b/docs/source/build.rst index 55a7444..78ce187 100644 --- a/docs/source/build.rst +++ b/docs/source/build.rst @@ -1,4 +1,5 @@ .. _build: + Building iDaVIE from source =========================== @@ -50,6 +51,7 @@ Prerequisites - Make sure to note the path to the vcpkg root folder, found at :literal:`C:\\\\vcpkg` for default installations. 5. Install Steam and SteamVR + - To use iDaVIE with any VR headset, we use Steam's SteamVR application as a bridge. - Download the `Steam installer `_ and install it. Create a Steam account if you do not already have one (no cost to create). - Install `SteamVR `_ by clicking the "Play Game" button on the SteamVR page. @@ -74,6 +76,7 @@ Prerequisites - From the Unity Hub, select the ``Add`` button and click ``Add project from disk`` (only necessary the first time). Navigate to where you downloaded the iDaVIE source code in step 5 and select the iDaVIE folder. - Once the project is opened, navigate to ``Assets/Scenes/`` in the Editor's navigation window (at the bottom) and double-click on the ui.unity file. - Under **Window->SteamVR Input**, click the **Save and generate** button. + .. raw:: html Build Settings**. + .. raw:: html + - Click on the Player Settings button on the bottom left. + .. raw:: html + - Under XR Plug-in Management (scroll down on the left), make sure that OpenVR Loader is selected in the list of Plug-in Providers. + .. raw:: html + - Click the **Build** button and select your destination folder. Troubleshooting diff --git a/docs/source/conf.py b/docs/source/conf.py index 42e58c0..66c0cd5 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -22,9 +22,9 @@ author = u'IDIA Vislab, INAF-OACT' # The short X.Y version -version = u'1.0' +version = u'1.1' # The full version, including alpha/beta/rc tags -release = u'1.0' +release = u'1.1.0' # -- General configuration --------------------------------------------------- @@ -65,14 +65,7 @@ # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] -# html_logo = "./_static/vislab_logo.png" -# html_logo = "./_static/vislab_logo_alt.png" -# html_logo = "./_static/iDaVIElogo_V3.jpg" -# html_logo = "./_static/iDaVIElogo_V3_NoCorn.png" html_logo = "./_static/iDaVIElogo_New.png" -# html_logo = "./_static/iDaVIElogo_V4_transbg.png" -# html_logo = "./_static/iDaVIElogo_V4.jpg" -# html_logo = "./_static/iDaVIElogo_V5.jpg" # Custom sidebar templates, must be a dictionary that maps document names # to template names. diff --git a/docs/source/develop.rst b/docs/source/develop.rst index 16a00a7..218df9a 100644 --- a/docs/source/develop.rst +++ b/docs/source/develop.rst @@ -23,17 +23,20 @@ Set up UnityYamlMerge --------------------- To facilitate the merging of separate branches that include merge conflicts in scene (``*.unity``) files in iDaVIE, Unity provides a mergetool called UnityYamlMerge. This requires a few set up steps before it can be used. - 1. First, the iDaVIE repo should be told to use UnityYamlMerge as the mergetool. Add the following lines to the ``.git\config`` file. Note the escaped slash ``\\`` for folder divisors -- it will not work otherwise. + 1. First, the iDaVIE repo should be told to use UnityYamlMerge as the mergetool. Add the following lines to the ``.git\config`` file. Note the escaped slash ``\\`` for folder divisors -- it will not work otherwise. :: + [mergetool "UnityYamlMerge"] - cmd = '\\Unity\\2021.3.47f1\\Editor\\Data\\Tools\\UnityYAMLMerge.exe' merge -p "$BASE" "$REMOTE" "$LOCAL" "$MERGED" - trustExitCode = false + cmd = '\\Unity\\2021.3.47f1\\Editor\\Data\\Tools\\UnityYAMLMerge.exe' merge -p "$BASE" "$REMOTE" "$LOCAL" "$MERGED" + trustExitCode = false [merge] - tool = UnityYamlMerge + tool = UnityYamlMerge + 2. In the folder ``\Unity\2021.3.47f1\Editor\Data\Tools``, open the ``mergespecfile.txt`` text file. This file contains the fallback mergetools if UnityYamlMerge cannot resolve the conflicts or filetypes. Here we recommend VSCode as the fallback. Add the following lines to the ``mergespecfile.txt`` file. Note that ``code`` is likely in the system PATH if VSCode is installed, otherwise the path of the ``code.exe`` executable is required. :: - ``# VSCode - * use code --wait "%r" "%l" "b" "%d"`` + + # VSCode + * use code --wait --merge "%l" "%r" "%b" "%d" Merging procedure ----------------- diff --git a/docs/source/future.rst b/docs/source/future.rst index 4596a14..c57d45b 100644 --- a/docs/source/future.rst +++ b/docs/source/future.rst @@ -9,17 +9,14 @@ In the **short** term, we list features that we are actively working on and will Short-term ---------- -* Addressing bugs that arise after the release of 1.0. -* Adding the ability to load a subcube. That is, load a contiguous portion of the cube, specified by the user by providing the bounds of the subcube. This includes a major rework of all file operations. See the relevant `pull request `_, `branch `_, and `discussion `_ for more information. -* Adding the ability to select a different HDU (rather than the first). Some instruments, noticeably integral field spectrographs (IFUs) such as MUSE, NIRSpec, or MIRI, produce cubes where the data is stored in the second HDU. To load this, the rework mentioned for adding subcubes is required. Therefore it will be added along with that feature. See the relevant `issue `_ and `branch `_ for more information. +* Improve the performance of the scripted video rendering. +* Separate the visualisation from the analysis tools. At the moment, much of the radio astronomy analysis tools and the visualisation are hardcoded together, such as the menus. The actual analysis code is contained within a `.dll` plugin. Unity allows for dynamically created menus (see the generic popups in the subcube `pull request `_), which opens the possibility of moving all analysis tools into a separate plugin, while the visualisation code remains as is. Creators of the analysis tools can then potentially specify their menus through a script or API file, while iDaVIE (the visualisation tool) creates the menus dynamically from prefabs. More work will be required to look at how Unity deals with dynamic code, as well as a major refactor once the framework is made possible. This will be of significacnt use in the multidisciplinary domain, allowing the end user to download iDaVIE the visualisation tool and the analysis plugin relevant to their field. See the related `issue `_ and `discussion `_ for more information. +* Release a version of iDaVIE that allows for particle datasets to be visualised. In particular, sparse multiparameter datasets, such as simulations, benefit greatly from visualisation in VR. A prototype has been created and sample images can be found on our `documentation pages `_. A publicly available prototype will be available in due course. Medium-term ----------- * Allow users to switch between rendering for emission or absorption. At the moment, the rendering shader (a ray-marching algorithm) samples values along the ray and returns either the maximum or the average value. To account for absorption in the foreground, a new shader will have to be developed, possibly based on `radiative transfer `_ equations. See the relevant `issue `_ and `discussion `_ for more information. -* Release a version of iDaVIE that allows for particle datasets to be visualised. In particular, sparse multiparameter datasets, such as simulations, benefit greatly from visualisation in VR. A prototype has been created and sample images can be found on our `documentation pages `_. A publicly available prototype will be available in due course. -* Create a scripting language or API to allow for smooth videos flying through the data to be generated. Currently, recording the user's view of the data is done through recording the screen showing the view of one of the user's eyes. This is invariably jittery and not of good quality. Recording a video from a Unity camera moving through the data results in smoother and better quality video. A prototype was created that utilised a hard-coded route for the camera to follow. It is desirable to create a way for the user to control the movement of this camera, without sacrificing the quality. One way to do this would be by having a script with commands that the camera will follow, and a button on the desktop interface to have it execute. See the `relevant `_ `issues `_ and `discussion `_ for more information. * Allow for a movable projection plane that highlights a 2D cross-section in a separate window, akin to the existing moment maps feature. This can be a single channel, or a position-velocity graph, or potentially overlaying one dataset on another. See `the `_ `relevant `_ `issues `_ and `discussion `_ for more information. -* Separate the visualisation from the analysis tools. At the moment, much of the radio astronomy analysis tools and the visualisation are hardcoded together, such as the menus. The actual analysis code is contained within a `.dll` plugin. Unity allows for dynamically created menus (see the generic popups in the subcube `pull request `_), which opens the possibility of moving all analysis tools into a separate plugin, while the visualisation code remains as is. Creators of the analysis tools can then potentially specify their menus through a script or API file, while iDaVIE (the visualisation tool) creates the menus dynamically from prefabs. More work will be required to look at how Unity deals with dynamic code, as well as a major refactor once the framework is made possible. This will be of significacnt use in the multidisciplinary domain, allowing the end user to download iDaVIE the visualisation tool and the analysis plugin relevant to their field. See the related `issue `_ and `discussion `_ for more information. Long-term --------- diff --git a/docs/source/gui.rst b/docs/source/gui.rst index 2dc7b27..be39480 100644 --- a/docs/source/gui.rst +++ b/docs/source/gui.rst @@ -31,17 +31,21 @@ The FILE tab is what the user will see when iDaVIE is opened. This tab includes .. raw:: html - -1) Button to display the desktop :literal:`VR View`. This is the view that the user will see when the VR headset is worn. VR View is activated by default upon loading the cube. -2) Button to display more iDaVIE information. This includes the version of the software, the authors, and the license. -3) Button to exit iDaVIE. -4) Click this Browse button to open the file explorer and select the cube file to load. -5) The header information for the selected data cube will be displayed here. -6) Optionally, you can click the Browse button to open the file explorer and select a mask file to load. **NOTE:** the mask must have the exact same dimensions of the cube loaded. -7) Click the Load button to start the rendering of the cube. A loading bar will appear at the bottom of the window to indicate load progress. Once this is done, the user can put on the headset and start exploring the cube. - +#. The version of this build of iDaVIE. Useful when reporting errors or bugs. +#. Button to display the desktop :literal:`VR View`. This is the view that the user will see when the VR headset is worn. VR View is activated by default upon loading the cube. +#. Button to display more iDaVIE information. This includes the version of the software, the authors, and the license. +#. Button to exit iDaVIE. +#. Click this Browse button to open the file explorer and select the cube file to load. +#. This dropdown menu allows you to select which HDU in the FITS file the data is saved in. This will only appear if the file contains more than one HDU. +#. The header information for the selected data cube (and HDU, if relevant) will be displayed here. +#. Optionally, this checkbox can be checked if you desire to load only a portion of the data file. This will open the section below. +#. These input fields specify the bounds of the subcube to be loaded from the data file. Each axis can have separate bounds specified. +#. Optionally, you can click the Browse button to open the file explorer and select a mask file to load. **NOTE:** the mask must have the exact same dimensions of the cube loaded. +#. Click the Load button to start the rendering of the cube. A loading bar will appear at the bottom of the window to indicate load progress. Once this is done, the user can put on the headset and start exploring the cube. +#. This message displays the status of the loading process, useful for when loading a large cube. RENDER tab ^^^^^^^^^^ @@ -50,7 +54,7 @@ The RENDER tab includes options to tune the rendering parameters of the cube. .. raw:: html - 1) Dropdown menu to set a precalculated size for the cube side lengths. The default is :literal:`X=Y=Z`, setting the cube to 1x1x1 size. The other option of :literal:`X=Y` sets the X and Y lengths of the cube equal (to be a square) and sets the Z length to have the same ratio as the X and Z lengths of the data cube. @@ -68,7 +72,7 @@ The STATS tab includes options to check and interact with some basic data statis .. raw:: html - @@ -89,7 +93,7 @@ The SOURCES tab includes options to load a catalog of sources. The catalog can b .. raw:: html - 1) Click this Browse button to open the file explorer and select the catalog file to load. @@ -111,7 +115,7 @@ The DEBUG tab includes a readout of the debug log for the current session. This .. raw:: html - @@ -126,7 +130,7 @@ After loading a file in the FILE tab, the user can put on the headset. The first .. raw:: html - The axes are RGB colour-coded as (for example): @@ -143,7 +147,7 @@ The Quick menu is the main menu the user will interact with in the VR environmen .. raw:: html - 1) Open the :ref:`sourcelist`. @@ -152,11 +156,12 @@ The Quick menu is the main menu the user will interact with in the VR environmen 4) Open the :ref:`settings`. 5) Open the :ref:`colourmap`. 6) Open the :ref:`maskpainting` and start mask painting mode. -7) Save the mask to file. -8) Toggle to crop the cube to the selected region or uncrop the cube if already cropped. -9) Toggle the mask application options (voice command analogue in brackets). Options are to subtract the unmasked regions ("mask on"), subtract the masked regions ("mask invert"), show the mask by itself ("mask isolate"), or show the cube without the mask ("mask off"). -10) Take a screenshot of the current view. -11) Exit iDaVIE. +7) Toggle to crop the cube to the selected region or uncrop the cube if already cropped. +8) Toggle the mask application options (voice command analogue in brackets). Options are to subtract the unmasked regions ("mask on"), subtract the masked regions ("mask invert"), show the mask by itself ("mask isolate"), or show the cube without the mask ("mask off"). +9) Take a screenshot of the current view. +10) Open the :ref:`videoMakerUI` to record perspectives for making scripted videos. +11) Save the mask to file. +12) Exit iDaVIE. .. _maskpainting: @@ -169,7 +174,7 @@ In the mask painting mode, the user can paint the mask using the controllers. Th .. raw:: html - 1) Activate additive brush mode. This allows the user to add to the mask by painting with the primary controller. The value of the mask is set to the current Source ID that will be indicated at the top of the menu. @@ -198,7 +203,7 @@ This window displays the three types of sources that can be used with iDaVIE: ma .. raw:: html - 1) Button to select the indicated source. @@ -232,13 +237,13 @@ The Source Info window displays the information of the selected source. This inc .. raw:: html - 1) The number of the source in its list. 2) Information about the position of the source. This will either be the weighted **centroid** (in case of mask sources) or the physical **centre** of the box (in the case of imported and selection boxes). -3) The calculated sum of the data values for masked sources. This is the integrated intensity of the source. -4) The calculated peak data value of the masked source. +3) The calculated sum of the data values for masked sources (the beam size is not taken into account when calculating the sum). This is the integrated intensity of the source. +4) The calculated peak data value of the masked source (the beam size is not taken into account when calculating the peak). 5) The calculated the source's systemic velocity, or the velocity of its centroid (in voxel units). 6) The calculated spectral line width at 20% of the peak intensity of the source (in voxel units). 7) The calculated the source's systemic velocity, or the velocity of its centroid (in physical units). @@ -254,7 +259,7 @@ The Settings window allows the user to adjust the rendering settings of the cube .. raw:: html - 1) Arrow buttons to change the applied colour map of the cube. @@ -282,7 +287,7 @@ The Plots window gives the user access to useful 2D plots calculated in realtime .. raw:: html - @@ -314,7 +319,7 @@ The Keypad is a virtual keypad that can be used to input custom values for the m .. raw:: html - @@ -327,7 +332,7 @@ The Voice Command window displays the available voice commands that the user can .. raw:: html - 1) Click the arrow button to manually activate the voice command. @@ -335,20 +340,57 @@ The Voice Command window displays the available voice commands that the user can .. _colourmap: -Colourmap Winow -^^^^^^^^^^^^^^^ +Colourmap Window +^^^^^^^^^^^^^^^^ The Colourmap window displays the available colour maps that the user can apply to the cube. iDaVIE makes use of the colourmaps available in the matplotlib Python library. See the `matplotlib documentation `_ for more information on the available colour maps. .. raw:: html - 1) Click the arrow button to apply the colour map. 2) Use the scrolls buttons to scroll through the available colour maps. The list can also be scrolled by moving the thumbstick up and down while the laser pointer is hovering over the list. +.. _videoMakerUI: + +Videomaker Window +^^^^^^^^^^^^^^^^^ + +The Videomaker window provides access to tools used for generating a list of perspectives to be used when generating a video. + +.. raw:: html + + + +1) Toggle whether the recorded perspective are from the head position, or from the cursor position. The button image changes to show the current mode. +2) Open the :ref:`videomakerlistui`, showing the list of perspectives created in this session. +3) Export the list of perspectives to a new :literal:`.idvs` script file. This file is saved under :literal:`Output/VideoScripts/_VideoScript_yyyyMMdd_Hmmss.png`, where :literal:`` is the file name of the loaded data cube, and :literal:`yyyyMMdd_Hmmss` is the timestamp when the file is saved. +4) Exit video recording mode and close this menu. + +.. _videoMakerListUI: + +Videomaker Perspective List +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The Videomaker list of points displays all the perspectives recorded in the current session, allowing users to revisit or delete perspectives as they wish. + +.. raw:: html + + + +1) Each point is either a head position, or a cursor position. +2) Each point has a default name, of the form :literal:`pN`, where N is the index of the point in the list. +3) Each point has a location relative to the data cube, as well as a rotation. Cursor locations have a rotation of (0, 0, 0). +4) Teleport the cube to reflect the perspective as stored in this head position. +5) Highlight this cursor position by drawing a cyan box around the stored location in the data cube. Click again to remove. +6) Remove this point from the list of perspectives. + +.. _cursorinfo: Controller Cursor Info ---------------------- @@ -357,21 +399,22 @@ The 3D cursor will provide information about the current voxel under the cursor. .. raw:: html - 1) The cursor itself is a small sphere that will follow the controller position. When inside the cube, individual voxels will be highlighted by the cursor with a green outline. This indicates what voxel the information will be displayed for. -2) WCS sky coordinates of the voxel under the cursor. This will be calculated using information from the cube header. -3) WCS spectral coordinate of the voxel under the cursor. This will be calculated using information from the cube header. -4) Image coordinates of the voxel under the cursor. This is the voxel index in the cube and is 1-indexed. -5) Data value of the voxel under the cursor. The unit is determined by the cube header. -6) The alternate spectral coordinate of the voxel under the cursor. This is calculated using the rest frequency of the cube and the spectral coordinate. -7) The red microphone icon indicates that voice commands are currently inactive. This could be due to the user being in **push-to-talk** mode without the talk button (secondary thumb button on primary controller) pressed or the iDaVIE window is not in focus. -8) iDaVIE window focus indicator. This will be present if the iDaVIE window is not in focus. This can be resolved by clicking on the iDaVIE window on the desktop. If this is present, voice commands will not be active. -9) The Source ID of the voxel under the cursor. This will not be visible if the voxel is not part of a mask source. -10) The green microphone icon indicates that voice commands are currently active. This will be present when the user is in **push-to-talk** mode and the talk button is pressed. -11) While in threshold adjustment mode, the Min value is displayed here. This is the minimum data value both where the colourmap will start and where the alpha value will be 0. -12) While in threshold adjustment mode, the Max value is displayed here. This is the maximum data value both where the colourmap will end and where the alpha value will be 1. -13) While in selection mode, the Region shows the voxel dimensions of the selected region. -14) While in selection mode, the Angle shows the calculated angle across the sky of the selected region. The angle will be from corner to corner of the selection box (start to end). -15) While in selection mode, the Depth shows the calculated depth of the selected region. This is the distance between the start and end of the box in the Z direction. \ No newline at end of file +2) WCS sky coordinates of the voxel under the cursor. This is calculated using information from the cube header. +3) WCS spectral coordinate of the voxel under the cursor. This is calculated using information from the cube header. +4) World coordinates of the voxel under the cursor. This is the voxel index of the data displayed, and is 1-indexed. This is only equivalent to the index in the data if the data loaded has the same left corner as the full cube. +5) Data coordinates of the voxel under the cursor. This is the voxel index in the cube and is 1-indexed. This will only be present if a subcube is loaded. +6) Data value of the voxel under the cursor. The unit is determined by the cube header. +7) The alternate spectral coordinate of the voxel under the cursor. This is calculated using the rest frequency of the cube and the spectral coordinate. +8) The red microphone icon indicates that voice commands are currently inactive. This could be due to the user being in **push-to-talk** mode without the talk button (secondary thumb button on primary controller) pressed or the iDaVIE window is not in focus. +9) iDaVIE window focus indicator. This will be present if the iDaVIE window is not in focus. This can be resolved by clicking on the iDaVIE window on the desktop. If this is present, voice commands will not be active. +10) The Source ID of the voxel under the cursor. This will not be visible if the voxel is not part of a mask source. +11) The green microphone icon indicates that voice commands are currently active. This will be present when the user is in **push-to-talk** mode and the talk button is pressed. +12) While in threshold adjustment mode, the Min value is displayed here. This is the minimum data value both where the colourmap will start and where the alpha value will be 0. +13) While in threshold adjustment mode, the Max value is displayed here. This is the maximum data value both where the colourmap will end and where the alpha value will be 1. +14) While in selection mode, the Region shows the voxel dimensions of the selected region. +15) While in selection mode, the Angle shows the calculated angle across the sky of the selected region. The angle will be from corner to corner of the selection box (start to end). +16) While in selection mode, the Depth shows the calculated depth of the selected region. This is the distance between the start and end of the box in the Z direction. \ No newline at end of file diff --git a/docs/source/how_to_demos.rst b/docs/source/how_to_demos.rst index 9f52e3f..c1d0572 100644 --- a/docs/source/how_to_demos.rst +++ b/docs/source/how_to_demos.rst @@ -86,15 +86,93 @@ iDaVIE allows the user to investigate the basic statistics of the cube and to cr style="width:560px; height:315px;">
-Create a movie (using external tools) -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Create a movie using iDaVIE +^^^^^^^^^^^^^^^^^^^^^^^^^^^ +iDaVIE provides an extensive video recording mode, with more detail available at :ref:`videoMaker`. -We have found the best way to record sessions in iDaVIE is by activating the VR View window in the SteamVR Status menu: +.. raw:: html + + + + +Desktop Selection +^^^^^^^^^^^^^^^^^^^^^ + +Overview +-------- + +The desktop selection method introduces a way of masking sources without the use of a VR headset. This method allows you to move through your data slice by slice, circling regions of interest as you progress. Note: this method does not replace the VR selection methods but rather supplements it, the software needs an active headset to run. + +How to use Desktop Selection +---------------------------- + +The desktop interface is integrated into the already existing desktop UI for iDaVIE-v. Once a file is loaded you simply can select the “Paint” tab to enter the desktop selection mode: + +.. raw:: html + + + +User Interface for Desktop Selection +------------------------------------ + +The desktop selection interface, as shown above, has two primary components. The first being the left half of the screen which represents a 2D slice of the data that you are currently viewing. This is where you can draw to make selections. Below are several buttons relating to actions that can be performed on this window. The right half of the screen displays several settings that can be toggled, described from top to bottom in the following table: + ++-----------------------+---------------------------------------------------------------+ +| Setting | Description | ++=======================+===============================================================+ +| Slice slider | Allows you to move between slices. The left and right arrow | +| | keys can also be used for this. | ++-----------------------+---------------------------------------------------------------+ +| Axis | Allows you to change which axis the slices are moving through.| ++-----------------------+---------------------------------------------------------------+ +| Source ID | Allows you to set the source ID, or add new sources. | ++-----------------------+---------------------------------------------------------------+ +| Colour Map | Allows you to change the colour map the data is rendered in. | ++-----------------------+---------------------------------------------------------------+ +| Selection Mode | Similar to shape selection, allows you to toggle between | +| | additive and subtractive selection. | ++-----------------------+---------------------------------------------------------------+ +| Save Mask | Options for saving a mask. | ++-----------------------+---------------------------------------------------------------+ +| VR View | Gives a view of the data in 3D to represent which slice of the| +| | data is currently being displayed. | ++-----------------------+---------------------------------------------------------------+ + +Flow for Desktop Selection +-------------------------- + +Once the desktop selection is open, you would begin by moving to the slice of the source you wish to begin painting. Once there, you simply use your mouse with the left click to draw an enclosed region around the source: + +.. raw:: html + + + +Once you are happy, you can either press the Apply Mask button or Space Bar to confirm your selection. The outline will then turn yellow to indicate the selection has taken place: .. raw:: html - + + +Now, you may not be completely happy with the selection you made. You can either press undo to undo the drawing, or clear to clear all sources with the current source ID on that slice. Alternatively, you can swap to subtractive mode and draw to remove part of your selection: + +.. raw:: html + + + +.. raw:: html + + + +Now, if you want to isolate a separate source you can add a new source ID by pressing the + button next to the source ID dropdown. You will notice that the new source you identified is now yellow and the previous source is orange. The yellow indicates the source matching the currently selected source ID. + +.. raw:: html + + + +For ease of use, when you traverse to the next slice and find that the sources are similar to the previous slice, you can simply press the Previous Mask button or P on your keyboard to copy the masks you drew in the previous slice over to the next: + +.. raw:: html -An external screen recorder can then be used to capture the contents of the VR View window. For this, we recommend users download OBS Studio (https://obsproject.com/download). OBS Studio is a free and open-source software for video recording and live streaming. By setting the recording window to the VR View window, users can record their iDaVIE sessions. + +Finally, once you are happy with your mask you can save it as a new mask or overwrite a previously uploaded mask file. \ No newline at end of file diff --git a/docs/source/how_to_interac.rst b/docs/source/how_to_interac.rst index 07a82eb..916e4e5 100644 --- a/docs/source/how_to_interac.rst +++ b/docs/source/how_to_interac.rst @@ -221,11 +221,4 @@ In VR, the use of the controllers can become tricky, so we have implemented a se source ID (if a mask is loaded). .. note:: * A full list of colour maps is available from the quick menu, the options here are merely those available from voice commands. -.. WARNING:: We are aware that the voice commands do not work when the user is recording a movie using an external software. In this case the user should use the menu options. See more in the section :ref:`how_to_demos`. - - - - - - - +.. WARNING:: We are aware that the voice commands do not work when the user is recording a movie using an external software. In this case the user should use the menu options. See more in the section :ref:`how_to_demos`. \ No newline at end of file diff --git a/docs/source/idvs_ref.rst b/docs/source/idvs_ref.rst new file mode 100644 index 0000000..dc6cc18 --- /dev/null +++ b/docs/source/idvs_ref.rst @@ -0,0 +1,305 @@ +.. _idvs_ref: + +IDVS Scripting Language Reference +--------------------------------- + +**Version:** 1.0 +**Purpose:** +The IDVS scripting language is used to control video recordings — defining camera positions, movements, and global recording settings. +Each line in an IDVS script defines one instruction or configuration. + +Table of Contents +^^^^^^^^^^^^^^^^^ + +1. `Basic Rules`_ +2. `Script Structure`_ +3. `Position Declarations`_ +4. `Commands`_ + - `Start`_ + - `Wait`_ + - `Move`_ + - `Rotate`_ +5. `Settings`_ +6. `Error Handling`_ +7. `Tips and Best Practices`_ +8. `Example Full Script`_ +9. `Summary of Commands`_ + +Basic Rules +^^^^^^^^^^^ + +* Each instruction must be written **on its own line**. +* **Blank lines** are allowed (ignored). +* **Comments** start with ``#`` and continue to the end of the line. +* Commands are **case-sensitive**. +* Indentation and extra spaces are ignored. +* Files exported from iDaVIE contain a number of comments explaining basic functionality. + +**Example:** + +.. code-block:: text + + # This is a comment + Start at introPosition + Wait 3 seconds + +Script Structure +^^^^^^^^^^^^^^^^ + +An IDVS script generally contains three types of statements: + ++---------------------------+--------------------------------------------------------------+ +| **Type** | **Description** | ++===========================+==============================================================+ +| | Define named 3D positions and orientations used by movement | +| **Position declarations** | and rotation commands. These positions are exported from the | +| | iDaVIE video location mode. | ++---------------------------+--------------------------------------------------------------+ +| **Commands** | Control camera actions (start, move, wait, rotate, etc.). | ++---------------------------+--------------------------------------------------------------+ +| **Settings** | Configure global video options (logo placement, quality). | ++---------------------------+--------------------------------------------------------------+ + + +Position Declarations +^^^^^^^^^^^^^^^^^^^^^ + +Define a named camera position and orientation. **Note**: these positions will almost always be exported from the iDaVIE video mode. + +**Syntax:** + +.. code-block:: text + + is {[X,Y,Z],[x,y,z]} + +**Parameters:** + +- ```` — name used later in the script (letters/numbers/underscores only). These will be `p1`` to `pN` when exported from iDaVIE's video mode. +- ``[X,Y,Z]`` — camera position in 3D space +- ``[x,y,z]`` — camera rotation (in degrees) + +**Example:** + +.. code-block:: text + + p1 is {[0,0,0],[0,0,0]} + p2 is {[10,5,0],[0,180,0]} + +**Notes:** + +- Parentheses ``()`` can be used instead of square brackets ``[]``. +- Redeclaring an alias overwrites the old one (warning issued). + +Commands +^^^^^^^^ + +*Start* +_______ + +Sets the initial camera position. + +**Syntax:** + +.. code-block:: text + + Start at + +**Example:** + +.. code-block:: text + + Start at p1 + +*Wait* +______ + +Pauses the camera movement for a given duration. + +**Syntax:** + +.. code-block:: text + + Wait seconds + +**Example:** + +.. code-block:: text + + Wait 2 seconds + +*Move* +______ + +Moves the camera from the current position to a defined destination. + +**Syntax:** + +.. code-block:: text + + Move in to over seconds + +**Parameters:** + +- ```` — movement interpolation method (e.g., ``LINE``, ``ARC``.) +- ```` — destination position (must be defined earlier) +- ```` — time duration of the move + +**Example:** + +.. code-block:: text + + Move in LINE to target over 5 seconds + +**Error Conditions:** + +- Unknown method → *“Invalid move method”* +- Unknown position alias → *“Invalid position alias”* + +*Rotate* +________ + +Rotates the camera around a defined position. +Several variants are supported for specifying timing and rotation behavior. + ++---------------------------------+--------------------------------------------------------------------------+ +| **Variant** | **Syntax** | ++=================================+==========================================================================+ +| **Basic** | ``Rotate around times`` | ++---------------------------------+--------------------------------------------------------------------------+ +| **Turn** | ``Rotate around times turn seconds`` | ++---------------------------------+--------------------------------------------------------------------------+ +| **Orbit** | ``Rotate around times orbit seconds`` | ++---------------------------------+--------------------------------------------------------------------------+ +| **Full (turn + orbit)** | ``Rotate around times turn seconds orbit seconds`` | ++---------------------------------+--------------------------------------------------------------------------+ +| **Full (orbit + turn)** | ``Rotate around times orbit seconds turn seconds`` | ++---------------------------------+--------------------------------------------------------------------------+ + +**Examples:** + +.. code-block:: text + + Rotate around p3 3 times + Rotate around p2 2 times orbit 4 seconds + Rotate around p5 2 times turn 1 seconds orbit 3 seconds + +Settings +^^^^^^^^ + +Settings modify global video parameters. + +**Syntax:** + +.. code-block:: text + + : + +**Examples:** + +.. code-block:: text + + logopos: topRight + framerate: 25 + +**Valid Settings:** + ++---------------+-----------------------------+-------------------------------------------+ +| **Setting** | **Description** | **Values** | ++===============+=============================+===========================================+ +| ``logopos`` | Logo position in the video | ``topLeft``, ``topRight``, ``bottomLeft``,| +| | | or ``bottomRight`` | ++---------------+-----------------------------+-------------------------------------------+ +| ``Width`` | The width of the video. | Integer value. | ++---------------+-----------------------------+-------------------------------------------+ +| ``Height`` | The height of the video. | Integer value. | ++---------------+-----------------------------+-------------------------------------------+ +| ``Framerate`` | The framerate of the video. | Integer value. | ++---------------+-----------------------------+-------------------------------------------+ + +**Error Conditions:** + +- Invalid setting name → *“Invalid setting name”* +- Invalid logo position → *“Invalid logo position value”* +- Invalid number → *“Format exception”* + +Error Handling +^^^^^^^^^^^^^^ + +Errors encountered during parsing are reported in the iDaVIE log with the line number and a description. + +**Example:** + +.. code-block:: text + + Parse error in example.idvs:12: Invalid position alias `p999`. + +Warnings (e.g., redefined aliases) do not stop execution. + +Tips and Best Practices +^^^^^^^^^^^^^^^^^^^^^^^ + +* Define all positions **before** using them. +* Use **descriptive aliases** like ``intro``, ``outro``, or ``focusPoint``. + +Example Full Script +^^^^^^^^^^^^^^^^^^^ + +.. code-block:: text + + # Video settings + Height : 720 + Width : 1280 + FrameRate : 25 + LogoPos : BR + + # List of positions: + # Takes the form: + # is {, } + # Alias can be any combination of characters, excluding whitespace. + # Both location and direction are Vector3, printed in the form `(x, y, z)`, + # and are relative to the datacube's normalised position and rotation. + + p1 is {(0.009, -0.075, -1.555), (9.131, 359.630, 357.958)} + p2 is {(-0.008, -0.067, -0.695), (5.768, 359.589, 358.856)} + p3 is {(0.849, 0.026, -0.030), (4.458, 268.075, 358.467)} + p4 is {(0.221, -0.183, 0.055), (0.000, 0.000, 0.000)} + + # Script: + # Accepted commands (see documentation for details): + # - Start at + # - Wait seconds + # - Move in to over seconds + # - Methods allowed: (LINE, ARC) + # - Rotate around times + + Start at p1 + Wait 1 seconds + Move in LINE to p2 over 2 seconds + Move in ARC to p3 over 2 seconds + Wait 1 seconds + Rotate around p4 1 times + Wait 1 seconds + Move in ARC to p2 over 2 seconds + Move in LINE to p1 over 2 seconds + Wait 1 seconds + +---- + +Summary of Commands +^^^^^^^^^^^^^^^^^^^ + ++-------------+-------------------------------------------------------------+-----------------------------------------------+ +| **Command** | **Syntax** | **Purpose** | ++=============+=============================================================+===============================================+ +| **Position**| `` is {[X,Y,Z],[x,y,z]}`` | Define a camera position and rotation | ++-------------+-------------------------------------------------------------+-----------------------------------------------+ +| **Start** | ``Start at `` | Set initial camera position | ++-------------+-------------------------------------------------------------+-----------------------------------------------+ +| **Wait** | ``Wait seconds`` | Pause for ```` seconds | ++-------------+-------------------------------------------------------------+-----------------------------------------------+ +| **Move** | ``Move in to over seconds`` | Move camera to ```` | ++-------------+-------------------------------------------------------------+-----------------------------------------------+ +| **Rotate** | ``Rotate around times [turn ] [orbit ]`` | Rotate camera around a specific point | ++-------------+-------------------------------------------------------------+-----------------------------------------------+ +| **Setting** | ``: `` | Set a global configuration | ++-------------+-------------------------------------------------------------+-----------------------------------------------+ \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 254341a..99e3398 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -20,6 +20,8 @@ iDaVIE: immersive Data Visualisation Interactive Explorer gui.rst how_to_interac.rst how_to_demos.rst + videoMaker.rst + idvs_ref.rst contribute.rst future.rst build.rst diff --git a/docs/source/inputs_outputs.rst b/docs/source/inputs_outputs.rst index a58bc28..06746af 100644 --- a/docs/source/inputs_outputs.rst +++ b/docs/source/inputs_outputs.rst @@ -71,3 +71,5 @@ iDaVIE provides: * If a mask is loaded and modified in VR then it can be saved either overwriting the original mask **or** as a copy. In the former case the mask will be saved with the same name of the original mask and in the same directory, in the latter case the suffix :literal:`-copy.fits` will be added to the original mask name and the edited mask will be saved in the same directory as the original mask (e.g. the edited mask file name will then be :literal:`originalmaskname-copy.fits`). * If no mask is provided in input, but one is created in iDaVIE, then the created mask is saved in the same directory of the data cube and a suffix :literal:`-mask.fits` will be addedd to the cube name to indicate the maks file (e.g. the created mask file name will then be :literal:`originalcubename-mask.fits`). * Moment maps are saved to :literal:`Output/MomentMaps/Moment_map_[0/1]_yyyyMMdd_Hmmss.png`, where :literal:`yyyyMMdd_Hmmss` is the timestamp when the files are saved. +* **IDVS** iDaVIE Video Script created by iDaVIE, stored in :literal:`Output/VideoScripts`. Used to create videos. +* **MP4** videos created by iDaVIE using IDVS, stored in :literal:`Output/Video`. \ No newline at end of file diff --git a/docs/source/installation_and_configuration.rst b/docs/source/installation_and_configuration.rst index 164aa9f..b168c15 100644 --- a/docs/source/installation_and_configuration.rst +++ b/docs/source/installation_and_configuration.rst @@ -6,7 +6,7 @@ Installation and configuration Executable ----------- -Once the requirements described in :ref:`requirements`, are installed and working correctly, the user can download and unzip the provided :literal:`iDaVIE.1.0.zip`, which contains the executable .exe (and other reference files). The zip file is available on Github at this `link `_. +Once the requirements described in :ref:`requirements`, are installed and working correctly, the user can download and unzip the provided :literal:`iDaVIE-v1.1.zip`, which contains the executable .exe (and other reference files). The zip file is available on Github at this `link `_. .. raw:: html @@ -167,6 +167,8 @@ Config Options false uses a more informative text version. Default: ``true``. * - **importedFeaturesStartVisible** - Imported sources start visible. Default: ``true``. + * - **numberOfLogsToKeep** + - The number of sessions' to keep the log files of. Default: ``5``. Moment Maps Config Options ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -237,11 +239,9 @@ In this section we share some useful tips where we found a solution to a known i #. Post an issue on the Github repository, or, #. Make contact with us and send us the log files along with your bug reports. The log files can be found in the directory :literal:`iDaVIE/Outputs/Logs`. - -.. WARNING:: Unity only allows for a maximum of two log files to be stored. Therefore, if a problem is encountered with iDaVIE, make sure to copy the log file to a different folder **BEFORE** starting a new iDaVIE session, otherwise the log file reporting the specific problem encountered will be lost. Known issues ------------ The following are issues we already know about and that will be fixed as soon as possible: -#. Problem with virus protection systems. We will make a request to Norton to have our software "whitelisted". In the meantime the virus protection does not recognize the .exe and puts up the warning. +#. Problem with virus protection systems. We have made a request to Norton to have our software "whitelisted". In the meantime the virus protection does not recognize the .exe and puts up the warning. diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index 67d94c1..04d04a8 100644 --- a/docs/source/introduction.rst +++ b/docs/source/introduction.rst @@ -1,6 +1,6 @@ Introduction ============ -.. note:: The software is in active development, and while all precautions are taken to ensure as smooth an experience as possible, some issues might still occur. We would appreciate a bug report. Please see :ref:`contribute` for more detail. +.. note:: The software is in active development, and while all precautions are taken to ensure as smooth an experience as possible, some issues might still occur. We would appreciate a bug report. Please see :ref:`contribution` for more detail. iDaVIE is a data visualisation tool for 3D volumetric data, with analysis tools aimed at astronomical data in particular (e.g. spectral line data cube analysis, such as HI or CO data cubes). It renders 3D volumetric data as a cube within VR space. This provides profound insight for a multitude of scientific disciplines. While our focus has been on astronomical data and the included analysis tools are tailored to that domain, the visualisation on its own provides substantial benefit to other disciplines. This includes 3D models of neurological systems constructed from MRI images and 3D models of ice cores constructed from microscope images. See :ref:`multidisciplinary` for showcase videos of iDaVIE in use. diff --git a/docs/source/videoMaker.rst b/docs/source/videoMaker.rst new file mode 100644 index 0000000..3f38cd7 --- /dev/null +++ b/docs/source/videoMaker.rst @@ -0,0 +1,111 @@ +.. _videoMaker: + +Recording videos in iDaVIE +========================== + +With iDaVIE you can create smooth videos of your data using iDaVIE Video Scripts (IDVS). +This page details each step of this process: recording video positions in VR, to editing the IDVS generated from this, to loading this script in the desktop interface and creating the video. +Before this, the requirements for using the video feature are discussed. + + +Requirements +------------ + +To create videos, iDaVIE requires an `FFmpeg `_ executable. +You can download a pre-compiled FFmpeg executable from Windows `here `_. +Once you have downloaded the zipped files, extract them and store it in a location that you will remember, for example, your Documents folder. +iDaVIE will ask you to locate the FFmpeg executable later. + + +Recording video positions in VR +------------------------------- + +iDaVIE provides functionality that allows the user to capture perspectives within the VR space. These perspectives can be exported to a file, which can then be used to generate a stable and smooth video. + +.. raw:: html + + + +See :ref:`videomakerui` for an explanation of the UI elements used for this functionality. + +---- + +IDVS Scripting Language +----------------------- + +The IDVS scripting language is used to control video recordings — defining camera positions, movements, and global recording settings. +Each line in an IDVS script defines one instruction or configuration. Exporting a list of perspectives from the VR generates an :literal:`.idvs` file with a list of positions defined and basic scaffolding for a complete IDVS script. + +A full reference and documentation for the language can be found at :ref:`idvs_ref`. A summary of commands are presented below. + +Example Script +^^^^^^^^^^^^^^ + +The video below showcases a number of viewpoints and methods to move around the datacube. The source code for this video can be found on `the main repository `_. + +.. raw:: html + + + +Summary of Commands +^^^^^^^^^^^^^^^^^^^ + ++-------------+-------------------------------------------------------------+-----------------------------------------------+ +| **Command** | **Syntax** | **Purpose** | ++=============+=============================================================+===============================================+ +| **Position**| `` is {[X,Y,Z],[x,y,z]}`` | Define a camera position and rotation | ++-------------+-------------------------------------------------------------+-----------------------------------------------+ +| **Start** | ``Start at `` | Set initial camera position | ++-------------+-------------------------------------------------------------+-----------------------------------------------+ +| **Wait** | ``Wait seconds`` | Pause for ```` seconds | ++-------------+-------------------------------------------------------------+-----------------------------------------------+ +| **Move** | ``Move in to over seconds`` | Move camera to ```` | ++-------------+-------------------------------------------------------------+-----------------------------------------------+ +| **Rotate** | ``Rotate around times [turn ] [orbit ]`` | Rotate camera around a specific point | ++-------------+-------------------------------------------------------------+-----------------------------------------------+ +| **Setting** | ``: `` | Set a global configuration | ++-------------+-------------------------------------------------------------+-----------------------------------------------+ + +Previewing and Exporting videos +------------------------------- + +The interface for previewing and exporting IDVS to videos can be found in the RENDER tab of the iDaVIE desktop GUI. + +.. raw:: html + + + +1) The name of the IDVS currently loaded. +2) Button to find and load an IDVS, opens a file explorer. +3) Button to reload the current IDVS from disk. This is useful when making iterative changes to the current IDVS. +4) Button to play the video in "Preview" mode. The video will not be exported to a file, but performance is better than exporting. This button is only visible if an IDVS is loaded. +5) Button to "Export" the video to an mp4 file in :literal:`Output/Video`. A preview of the video is also show, however this preview may not be in real-time (depending on the frame-rate of the exported video) and performance will not be as good as Preview mode. This button is only visible if an IDVS is loaded. + +If you press the Preview button, the video will be previewed in the GUI: + +.. raw:: html + + + +1) View of the video being previewed. Replaces the usual VR View. +2) Text indicates "Preview" mode. If the Export button was pressed, this would display "Export Video". +3) Button to "Pause" the video preview. If pressed the video preview will be paused, and may be resumed by pressing the "Resume" button that replaces this. +4) Button to "Stop" the video preview. +5) The progress of the video. The text indicates if the video preview is "Playing" or if it is "Paused". +6) A slider to adjust the preview quality (resolution) of the video, provided in case of poor performance during preview. With the slider to the right, the video will be previewed at the full resolution as specified by the IDVS. With the slider towards the left, the video will preview at a lower resolution than this. The slider is only available during "Preview" mode and the slider position will not affect the output resolution of the video. + +When you are satisfied with the video preview, you may wish to export the video. +To do this, press the Export button. +The first time you press the Export button a file dialogue will pop-up asking you to "Open the FFmpeg executable". This will also happen if the FFMPEG install is no longer valid. +Navigate to the file location where you stored the FFmpeg folder, select the :literal:`bin/ffmpeg.exe` file. + +.. raw:: html + + + +The exported video can be found in :literal:`Output/Video`, and will have the same filename as the IDVS with an additional time-stamp at the end for when the video was made. + +.. WARNING:: If the data cube is too zoomed in or out, this can affect the video and you may need to go into VR to change the level of zoom. If the nearest parts of the cube are cut-off when the camera enters it, then you are probably too zoomed out (the cube is too small). Conversely, if distant parts of the cube are cut-off, then you are probably too zoomed in (cube is too big).