Merge pull request #40 from dneg/update_0_10_0

Release 0.10.0

Author: alatdneg

CMakeLists.txt

@@ -1,6 +1,6 @@
 cmake_minimum_required(VERSION 3.12 FATAL_ERROR)
 
-set(XSTUDIO_GLOBAL_VERSION "0.9.0" CACHE STRING "Version string")
+set(XSTUDIO_GLOBAL_VERSION "0.10.0" CACHE STRING "Version string")
 set(XSTUDIO_GLOBAL_NAME xStudio)
 
 project(${XSTUDIO_GLOBAL_NAME} VERSION ${XSTUDIO_GLOBAL_VERSION} LANGUAGES CXX)

docs/conf.py

@@ -75,9 +75,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.8.0'
+version = '0.10.0'
 # The full version, including alpha/beta/rc tags.
-release = '0.8.0'
+release = '0.10.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/user_docs/appendix/python_scripting.rst

@@ -33,8 +33,30 @@ Some simple python scripts are included with the xSTUDIO source code. These can
     API classes and methods include docstrings - query them using **help()** and **dir()**.
 
 
-Python Examples
-===============
+Python Plugins
+=================
+
+xSTUDIO now provides a Python plugin API. The features of this API are still being expanded (Q2 2023) but it is ready to be used for some purposes. For example, it's possible to create Viewport overlay graphics, add menu items to some of xSTUDIO's menus that execute callback methods in your plugin. You can create attributes on your python plugin class instance that can be exposed in the QML UI layer to, for example, add buttons to the toolbar or launch fully customised QML interfaces.
+
+To learn more about the plugin API we reccommend that you look at the examples available in the xSTUDIO source repository. These can be found in the **src/demos/python_plugins** subfolder. Note that the dnSetLoopRange is dependent on metadata that is specific to DNEG's pipeline but it is nevertheless commented for 3rd party users to refer to.
+
+To 'install' Python plugins you simply need to copy your plugins to an appropriate location and set the 'XSTUDIO_PYTHON_PLUGIN_PATH' environment variable to point to this location before running the xstudio binary. Typically at a studio sys-admins would advise on this and set-up appropriate wrapper scripts for xSTUDIO that ensure your environment variables are set. However, it's also very straightforward for an individual user. The env var should be a colon separated list of file system paths that include the python-importable module folder of your plugin(s).
+
+For example, let's say you have downloaded the xSTUDIO source repo to the a folder here /home/$USER/Dev/:
+
+.. code-block:: bash
+    :caption: Install the demo plugins and launch xSTUDIO to test them 
+
+    sudo mkdir -p /usr/local/lib/xstudio/python-plugins
+    cp -r /home/$USER/Dev/xstudio/src/demos/python_plugins/* /usr/local/lib/xstudio/python-plugins/
+    export XSTUDIO_PYTHON_PLUGIN_PATH=/usr/local/lib/xstudio/python-plugins
+    xstudio
+
+
+Python Scripting Examples
+=========================
+
+Aside from python 'plugins', which are essentially scripts that instance a custom plugin class to handle callbacks and manage certain typical communication with the core app, you also can do many things through straightforward scripts.
 
 **Here's a really basic example that prints out all the media paths in your session.**
 
@@ -72,35 +94,38 @@ Python Examples
     video = '/home/Media/some_quicktime.mov'
     audio = '/home/Media/some_audio.wav'
 
-    # create a playlist
-    playlist = XSTUDIO.api.session.create_playlist(name='My Playlist2')
 
-    # make the playlist the 'viewed' playlist 
-    XSTUDIO.api.session.set_on_screen_source(playlist[1])
+    # create a playlist - note the result is a pair, the first element is the 
+    # Uuid, the second is the Playlist class instance
+    playlist = XSTUDIO.api.session.create_playlist(name='My Playlist')[1]
+
+    # make the playlist the 'viewed' playlist
+    XSTUDIO.api.session.set_on_screen_source(playlist)
 
     # add a frames based source (eg. jpegs.0001.jpg, jpegs.0002.jpg etc.)
-    frames_based_media = playlist[1].add_media(frames)
+    frames_based_media = playlist.add_media(frames)
     # set the frame rate for the frames source
     frames_based_media.media_source().rate = FrameRate(30.0)
 
-    # add a combined audio/video 
-    video_only = playlist[1].add_media(video)
+    # add a containerised media item
+    video_only = playlist.add_media(video)
 
-    # add a combined audio/video 
-    combined = playlist[1].add_media_with_audio(video, audio)
+    # add a combined audio/video
+    combined = playlist.add_media_with_audio(frames, audio)
 
-    # add aan audio only source
-    audio_only = playlist[1].add_media(audio)
+    # add an audio only source
+    audio_only = playlist.add_media(audio)
 
-    # create a playhead for the playlist 
-    playlist[1].create_playhead()
-    playhead = playlist[1].playheads[0]
+    # get the playlist's playhead. Each playlist has its own playhead - by making
+    # it the 'active' (viewed) playhead below we can start playing media from the 
+    # playlist in the viewer.
+    playhead = playlist.playhead
 
     # get the 'playhead_selection' object, which is used to choose
-    # items from a playlist for playing 
-    plahead_selector = playlist[1].playhead_selection
+    # items from a playlist for playing
+    plahead_selector = playlist.playhead_selection
 
-    # select all the added media for playing (using their uuids) 
+    # select all the added media for playing (using their uuids)
     plahead_selector.set_selection(
         [
             frames_based_media.uuid,
@@ -109,6 +134,28 @@ Python Examples
             audio_only.uuid
             ])
 
+    XSTUDIO.api.app.set_viewport_playhead(playhead)
+
+    # Some components of xSTUDIO are built with the 'Module' base class. These 
+    # components have attributes which can be queried and modified through the API. 
 
-    # start playback 
+    # To inspect the attributes you can call the attributes_digest() method thus:
+    #
+    print("Viewport attrs: {0}".format(XSTUDIO.api.app.viewport.attributes_digest(verbose=True).dump(pad=2)))
+    print("Playhead attrs: {0}".format(playhead.attributes_digest(True).dump(pad=2)))
+
+    # By inspecting the attributes on the playhead, we can see the compare attr
+    # and it's options ... by setting to String the playhead will string together
+    # the selected media in a (most basic) sequence. Other options are 'A/B' or 'Off'.
+    playhead.set_attribute("Compare", "String")
+
+    # while we're at it let's set the viewport to 'Best' fit, so the whole image is
+    # fitted to the viewport area
+    XSTUDIO.api.app.viewport.set_attribute("Fit (F)", "Best")
+
+    # start playback
     playhead.playing = True
+
+    # We can also interact with the 'colour_pipeline' object (the OCIO colour 
+    # management plugin), for example
+    XSTUDIO.api.app.colour_pipeline.set_attribute("Exposure", 0.5)

docs/user_docs/conf.py

@@ -55,9 +55,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.9'
+version = '0.10'
 # The full version, including alpha/beta/rc tags.
-release = '0.9 (alpha)'
+release = '0.10 (alpha)'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/user_docs/overview.rst

@@ -11,7 +11,7 @@ xSTUDIO is a media playback and review application designed for professionals wo
 xSTUDIO is optimised to import and handle very large collections of media sources rapidly, loads specialised image formats and displays images with colour management. Users can quickly import, organise and group media into playlists and 'subsets', playing through and looping on media items and adding review notes and sketched annotations, allowing one to view the media in a highly interactive and collaborative way. This enables workflows that are essential for teams in VFX, animation and other post-production activities who need to see, on demand, the artwork that they and their colleagues are creating. For example one can jump between the viewed media source instantaneously, inspect pixels close-up, do frame-by-frame comparisons across multiple media sources, annotate the media with drawings and captions or add feedback notes to share.
 
 
-Current Version: v0.9 (alpha) - Overview
+Current Version: v0.10 (alpha) - Overview
 *****************************************
 
 This version of the application is a robust and high performance playback and review solution. xSTUDIO has been deployed at DNEG since September 2022 and is in daily use by thousands of VFX and Animation artists, supervisors and producers across our global teams to conduct image reviews.
@@ -46,7 +46,7 @@ Here are some key features for users that are available now:
     5. 'Snapshot' button allows you to save an annotation to disk as a jpeg /tiff etc image. 
   - Navigate your media collection through the notes interface by jumping directly to bookmarked frames.
 
-.. image:: ../images/interface-01.png
+.. image:: images/interface-01.png
 
 **The Viewer**
 

docs/user_docs/release_notes/index.rst

@@ -5,7 +5,7 @@ Release Notes
 =============
 
 ==============
-v0.9.0 (Alpha)
+v0.10.0 (Alpha)
 ==============
 
 This intial open source version of xSTUDIO should be considered as a 'preview' release as the development team get to grips with maintaining the code base on a public repo. There are still some major features under development so we expect some parts of the code to change and expand considerably. 

include/xstudio/atoms.hpp

@@ -29,6 +29,7 @@ const std::string colour_pipeline_registry{"COLOURPIPELINE"};
 const std::string embedded_python_registry{"EMBEDDEDPYTHON"};
 const std::string global_event_group{"XSTUDIO_EVENTS"};
 const std::string global_registry{"GLOBAL"};
+const std::string global_playhead_events_actor{"GLOBALPLAYHEADEVENTS"};
 const std::string global_store_registry{"GLOBALSTORE"};
 const std::string image_cache_registry{"IMAGECACHE"};
 const std::string keyboard_events{"KEYBOARDEVENTS"};
@@ -88,7 +89,6 @@ namespace colour_pipeline {
 } // namespace colour_pipeline
 
 namespace media {
-    class FrameRequestList;
     class MediaDetail;
     class MediaKey;
     class AVFrameID;
@@ -105,6 +105,7 @@ namespace media_reader {
     class AudioBufPtr;
     class ImageBufPtr;
     class MediaReaderManager;
+    class PixelInfo;
 } // namespace media_reader
 
 namespace thumbnail {
@@ -166,6 +167,7 @@ CAF_ALLOW_UNSAFE_MESSAGE_TYPE(xstudio::media::AVFrameIDsAndTimePoints)
 CAF_ALLOW_UNSAFE_MESSAGE_TYPE(xstudio::media_reader::AudioBuffer)
 CAF_ALLOW_UNSAFE_MESSAGE_TYPE(xstudio::media_reader::AudioBufPtr)
 CAF_ALLOW_UNSAFE_MESSAGE_TYPE(xstudio::media_reader::ImageBufPtr)
+CAF_ALLOW_UNSAFE_MESSAGE_TYPE(xstudio::media_reader::PixelInfo)
 CAF_ALLOW_UNSAFE_MESSAGE_TYPE(xstudio::ui::Hotkey)
 
 // clang-format off
@@ -198,6 +200,7 @@ CAF_BEGIN_TYPE_ID_BLOCK(xstudio_simple_types, first_custom_type_id)
     CAF_ADD_TYPE_ID(xstudio_simple_types, (xstudio::media_reader::AudioBufPtr))
     CAF_ADD_TYPE_ID(xstudio_simple_types, (xstudio::media_reader::ImageBufPtr))
     CAF_ADD_TYPE_ID(xstudio_simple_types, (xstudio::media_reader::MRCertainty))
+    CAF_ADD_TYPE_ID(xstudio_simple_types, (xstudio::media_reader::PixelInfo))
     CAF_ADD_TYPE_ID(xstudio_simple_types, (xstudio::playhead::CompareMode))
     CAF_ADD_TYPE_ID(xstudio_simple_types, (xstudio::playhead::LoopMode))
     CAF_ADD_TYPE_ID(xstudio_simple_types, (xstudio::playhead::OverflowMode))
@@ -406,6 +409,9 @@ CAF_BEGIN_TYPE_ID_BLOCK(xstudio_framework_atoms, xstudio_complex_types_last_type
     CAF_ADD_ATOM(xstudio_framework_atoms, xstudio::utility, version_atom)
 
     // **************** add new entries here ******************
+    CAF_ADD_ATOM(xstudio_framework_atoms, xstudio::global, get_global_playhead_events_atom)
+    CAF_ADD_ATOM(xstudio_framework_atoms, xstudio::module, attribute_uuids_atom)
+    CAF_ADD_ATOM(xstudio_framework_atoms, xstudio::global, get_actor_from_registry_atom)
 
 CAF_END_TYPE_ID_BLOCK(xstudio_framework_atoms)
 
@@ -524,7 +530,7 @@ CAF_BEGIN_TYPE_ID_BLOCK(xstudio_session_atoms, xstudio_plugin_atoms_last_type_id
     CAF_ADD_ATOM(xstudio_session_atoms, xstudio::playlist, get_media_atom)
     CAF_ADD_ATOM(xstudio_session_atoms, xstudio::playlist, get_media_uuid_atom)
     CAF_ADD_ATOM(xstudio_session_atoms, xstudio::playlist, get_next_media_atom)
-    CAF_ADD_ATOM(xstudio_session_atoms, xstudio::playlist, get_playheads_atom)
+    CAF_ADD_ATOM(xstudio_session_atoms, xstudio::playlist, get_playhead_atom)
     CAF_ADD_ATOM(xstudio_session_atoms, xstudio::playlist, insert_container_atom)
     CAF_ADD_ATOM(xstudio_session_atoms, xstudio::playlist, loading_media_atom)
     CAF_ADD_ATOM(xstudio_session_atoms, xstudio::playlist, media_content_changed_atom)
@@ -665,6 +671,10 @@ CAF_BEGIN_TYPE_ID_BLOCK(xstudio_playback_atoms, xstudio_session_atoms_last_type_
     // **************** add new entries here ******************
     CAF_ADD_ATOM(xstudio_playback_atoms, xstudio::playhead, last_frame_media_pointer_atom)
     CAF_ADD_ATOM(xstudio_playback_atoms, xstudio::colour_pipeline, display_colour_transform_hash_atom)
+    CAF_ADD_ATOM(xstudio_playback_atoms, xstudio::colour_pipeline, pixel_info_atom)
+    CAF_ADD_ATOM(xstudio_playback_atoms, xstudio::playhead, media_logical_frame_atom)
+
+
 
 CAF_END_TYPE_ID_BLOCK(xstudio_playback_atoms)
 
@@ -701,6 +711,8 @@ CAF_BEGIN_TYPE_ID_BLOCK(xstudio_ui_atoms, xstudio_playback_atoms_last_type_id+10
     CAF_ADD_ATOM(xstudio_ui_atoms, xstudio::ui::viewport, viewport_set_scene_coordinates_atom)
 
     // **************** add new entries here ******************
+    CAF_ADD_ATOM(xstudio_ui_atoms, xstudio::ui::viewport, enable_hud_atom)
+    CAF_ADD_ATOM(xstudio_ui_atoms, xstudio::ui::keypress_monitor, hotkey_atom)
 
 CAF_END_TYPE_ID_BLOCK(xstudio_ui_atoms)
 

include/xstudio/audio/audio_output_actor.hpp

@@ -67,5 +67,6 @@ class AudioOutputControlActor : public caf::event_based_actor {
     int video_frame_    = {0};
     int retry_on_error_ = {0};
     utility::Uuid uuid_ = {utility::Uuid::generate()};
+    utility::Uuid sub_playhead_uuid_;
 };
 } // namespace xstudio::audio

include/xstudio/audio/audio_output_device.hpp

@@ -28,6 +28,20 @@ class AudioOutputDevice {
      */
     virtual ~AudioOutputDevice() = default;
 
+    /**
+     *  @brief Open the connection to the sounding device
+     *
+     *  @details Note this will be called everytime audio playback starts
+     */
+    virtual void connect_to_soundcard() = 0;
+
+    /**
+     *  @brief Close the connection to the sounding device
+     *
+     *  @details Note this will be called everytime audio playback stops
+     */
+    virtual void disconnect_from_soundcard() = 0;
+
     /**
      *  @brief Query the soundcard for how many samples it would like to recieve for
      * playback

include/xstudio/bookmark/bookmark_actor.hpp

@@ -29,7 +29,7 @@ namespace bookmark {
 
         void build_annotation_via_plugin(const utility::JsonStore &anno_data);
 
-        void set_owner(caf::actor owner);
+        void set_owner(caf::actor owner, const bool dead = false);
 
 
       private: