Cxx examples

[darbyjohnston]

Fixes #917

This is WIP code to convert the Python examples to C++. I've successfully converted "summarize_timing.py" and started converting "flatten_video_tracks.py". With these changes, and the CMake variable OTIO_CXX_EXAMPLE set to "ON", you can run:

./examples/summarize_timing ../tests/sample_data/premiere_example.xml
./examples/flatten_video_tracks ../tests/sample_data/premiere_example.xml tmp.xml

Converting the examples brought up a couple of questions:

• It looks like the Python API has diverged a bit from C++? For example what are the C++ equivalents of each_clip() and deepcopy()?
• How should a user of the C++ API handle memory management? The "C++ Implementation Details" documentation mentions the use of possibly_delete() and Retainers?
• Can a user of the C++ API utilize the Python adapters for file I/O? I've implemented a utility class that provides this, and it seems to work OK initially, but is it the right approach? If so maybe the code should be moved into the OTIO library for general usage?

Note this code currently only works for Linux/macOS, there is some additional code that needs to be added for Windows.

[darbyjohnston]

I've updated the code to use Retainers and added the missing code for Windows.

[meshula]

This looks very helpful, I've dropped a few notes inline.

[meshula]

Might be an idea to mark this PR as "WIP" until it's ready to land? That's the convention we're using in this repo, in general, when things are being iterated and thought through.

[ssteinbach]

Rather than the wip tag, marking it as a draft PR is even better. Then we get a nice notification when its no longer draft.

[darbyjohnston]

Any thoughts about the Python functions each_clip() and deepcopy() for C++?

[meshula]

each_clip() and deepcopy() both seem handy for c++ use. Maybe a quick sketch and discussion if they should be a topic for a PR for OTIO? (Since deepcopy() is a Pythonism, I'd suggest deep_copy for C++.)

[darbyjohnston]

I've broken out the C++ code for using Python adapters into two separate examples, "python_adapters_child_process.cpp" and "python_adapters_embed.cpp", for using the adapters via child processes and an embedded Python interpreter respectively.

I think I prefer the embedding approach, that way there is less environment setup to worry about (making sure otioconvert is in the search path), and there is less platform specific code (child process creation and pipes seem more complicated on Windows).

I still need to take a look and see if I can get rid of the temporary files, and the flatten_video_tracks.cpp example is missing a C++ version of deepcopy().

@meshula Have you used CreateProcess() on Windows before? The MSDN documentation says to pass "cmd.exe" in to execute bat files, but I got the error "The system cannot find the file specified.". If I use "C:\windows\system32\cmd.exe" it works OK, but it seems like a bad idea to hard code the path...

[meshula]

The embedding approach is valid, but it's a whole other can of worms. Not everyone will want to bind Python into their application, because there's so much other environment to set up to make that fully functional. Embedded IS interesting, but so is calling out.

CreateProcess with a full path to system32\cmd.exe is actually fine; cmd has been there forever, and is unlikely to move in the foreseeable future. It's like the assumption that we make in expecting to be able to find sh at /bin/sh until the end of time.

[darbyjohnston]

OK, I've changed the example "python_adapters_embed.cpp" to use Python directly without needing temporary files. I did this by converting the timeline into JSON and passing that to/from Python where the adapters are used for file IO. It's a bit more code than before, but it's not too bad and doesn't require any platform specific code.

I also looked into deepcopy() and apparently it's just a wrapper around SerializableObject::clone(), so maybe it's not needed for C++. I updated the example "flatten_video_tracks.cpp" to use clone() and it should be complete now.

I think that addresses all of the feedback, should I "un-draft" this PR? Or should this also include C++ versions of the rest of the Python examples?

[ssteinbach]

Thanks for putting this together, @darbyjohnston. Both deepcopy and each_clip are based on pythonisms, and yeah -- deep copy() is just exposing the clone functionality. I wonder if each_clip would become a C++11 style iterator? Or are those just not good?

[meshula]

The interface for a C++ style iterator is not hard to satisfy; here's a nice overview. https://internalpointers.com/post/writing-custom-iterators-modern-cpp

That gives you compatibility with lots of STL features like std::copy, so iterators would be a definite nice-to-have.

[codecov-io]

Codecov Report

Merging #918 (cd4cfc1) into master (84af5e5) will decrease coverage by 0.22%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master     #918      +/-   ##
==========================================
- Coverage   85.96%   85.74%   -0.23%     
==========================================
  Files         184      191       +7     
  Lines       17892    18085     +193     
  Branches     1993     2044      +51     
==========================================
+ Hits        15381    15507     +126     
- Misses       2002     2055      +53     
- Partials      509      523      +14     

Flag	Coverage Δ
unittests	85.74% <ø> (-0.23%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
...ineio/opentime-bindings/opentime_timeTransform.cpp	90.00% <0.00%> (-10.00%)	⬇️
src/opentimelineio/clip.cpp	82.60% <0.00%> (-7.87%)	⬇️
src/opentimelineio/trackAlgorithm.cpp	70.00% <0.00%> (-7.78%)	⬇️
src/opentimelineio/transition.cpp	85.71% <0.00%> (-6.60%)	⬇️
src/opentimelineio/stackAlgorithm.cpp	80.85% <0.00%> (-5.52%)	⬇️
...entimelineio-bindings/otio_serializableObjects.cpp	91.74% <0.00%> (-3.38%)	⬇️
...pentimelineio/opentimelineio-bindings/otio_utils.h	73.77% <0.00%> (-2.04%)	⬇️
...ntimelineio/opentimelineio-bindings/otio_utils.cpp	80.68% <0.00%> (-1.88%)	⬇️
...lineio/opentime-bindings/opentime_rationalTime.cpp	95.89% <0.00%> (-1.55%)	⬇️
src/opentimelineio/serializableObject.h	88.88% <0.00%> (-1.50%)	⬇️
... and 27 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 84af5e5...cd4cfc1. Read the comment docs.

[darbyjohnston]

Un-drafting this since it seems like most of the feedback has been resolved and the other work for Retainers and each_clip() should probably be separate PRs...

[ssteinbach]

Looks good to me! Thanks @darbyjohnston!