From 80b22d50ac9195a69ce5163203e1b883c4021504 Mon Sep 17 00:00:00 2001 From: Nathan Rusch Date: Sun, 12 Aug 2018 23:33:53 -0700 Subject: [PATCH] Update README --- README.md | 97 ++++++++++++++++++++++++++++++------------------------- 1 file changed, 53 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 93edc1e..c3ecfbf 100644 --- a/README.md +++ b/README.md @@ -1,63 +1,72 @@ +# UsdQt -# usdQt +**Qt components for building custom USD tools** -## Reusable UI widgets for viewing and authoring USD files +## Project Goals -The components in usdview are good reference, but they’re purpose built for the usdview application and are implemented in a way that makes them difficult to extract. We need widgets that provide similar functionality that we can use ad-hoc throughout our pipeline. +The UI components that make up `usdview` are good reference for functionality, +but they’re purpose-built for the application, and are implemented in ways that +make them difficult to decouple from it. -### Project Goals -- make it easy to create standalione usdview-like applications, or integrate with client plugins (maya, katana, etc) -- long term, build a complete replacement of usdview +This project is meant to provide application components that can provide similar +(as well as new) functionality, to allow for ad-hoc use in custom tools. -### Design Requirements -- separate models and views -- standardize signals/slots between widgets -- support PySide2 -- optionally compatible with PyQt5/PyQt4/PySide +Longer-term, we hope this project will grow to the point that it can be used to +build a fully-functional `usdview` application. -### Project Status +## Contents -Usable, but under construction: We're in the process of melding existing efforts made at Luma and Pixar, so expect major refactoring to take place. +This project contains a mixture of pure Python and wrapped C++ code. All Qt code +is written in pure Python to avoid the need to link against Qt and get `moc` +involved in the build process. This may change in the future if deemed +beneficial/necessary. -## Components +The compiled extension module provides a set of helper classes that interface +with the USD C++ API to accelerate certain USD queries, operations, etc. -### Current -- **prim outliner**: view prim hierarchy - - similar to the outliner in usdview, but built on an MVC design - - includes editing capabilities: - - switch variants - - add references - - add Xforms -- **sublayer view**: view sub-layers and choose the current target -- **layer editor**: view usd ascii for current layer +#### Installed Python Packages -### Planned -- **variant set editor**: display and create variants and variant sets -- **stage signaler**: convert stage notifications into Qt signals -- **prim property editor**: view and edit properties/attributes of a prim -- **hydra viewport**: display changes to the stage in realtime +- `pxr.UsdQt`: Contains various Qt item data models, helper classes for building +UIs, and some other USD and Qt utility code. The `_bindings` module currently +contains all of the wrapped classes from the compiled extension module. +- `pxr.UsdQtEditors`: Contains various Qt UI elements. These range from +purpose-built display/editor widgets to an extensible outliner UI that also +serves as a good usage example for many of the utilities in `pxr.UsdQt`. +- `treemodel`: Contains a generic item tree and a Qt item model mixin that uses +it, which are used by some of the classes in `pxr.UsdQt`. -## Installing +## Building/Installation -First, install the dependencies: +The recommended (and currently only tested) way to build the project is using +CMake. A `setup.py` file is provided as well, but it has not been tested with +the most recent updates. -``` -pip install -r requirements.txt --user -``` +#### Build Requirements -Note that this assumes you have pyside/2 or pyqt4/5 installed. If you don't, then -run the following (and cross your fingers), or use homebrew: +- Boost Python +- USD +- TBB -``` -pip install PySide --user -``` +#### CMake Options -You'll also obviously need to make sure that you've built USD and placed the `pxr` python package on the `PYTHONPATH`. +- `INSTALL_PURE_PYTHON (BOOL)`: Whether to install the pure Python code in +addition to the compiled extension module. This defaults to `ON`. -## Testing +#### A note about `UsdQt.py` and `UsdQtEditors.py` -To test it out: +You may notice that the source contains `UsdQt.py` and `UsdQtEditors.py` files +alongside the package source directories. These are "shim" modules that we've +found to be very useful during the development of this project, as they enable +us to do more rapid editing and testing on the pure Python code without needing +to run a CMake build and install between each minor edit. They are not installed +with the project. -``` -python usdQt/app.py /path/to/file.usd -``` +## Using an alternate Qt API + +`UsdQt` expects the Qt API it uses to supply the PySide5/Qt5 module layout. + +By default, it will attempt to import and use `PySide2`. This can be overridden +by setting the `PXR_QT_PYTHON_BINDING` environment variable to the name of the +API package/module you wish to use instead. + +This works with the popular [Qt.py](https://github.com/mottosso/Qt.py) project.