#38: update readme, add quick start and changelog

README.md

@@ -1,31 +1,40 @@
-# houdini-cityengine-plugin
+# Palladio
 
-## Requirements
-- [SideFX Houdini 16.0](https://sidefx.com/download) (apprentice edition is supported)
-- [Esri CityEngine](http://www.esri.com/software/cityengine) with node-locked license
-- RHEL 6/7 (or compatible) with GCC 4.8
-- [cmake 3.8 or later](https://cmake.org/download)
-- [conan 0.29.1 or later](https://www.conan.io/downloads)
+Palladio is a plugin for [SideFX Houdini](https://www.sidefx.com). It provides custom operator nodes which enable the execution of [Esri CityEngine](http://www.esri.com/software/cityengine) rules within Houdini networks. This provides a convenient combination of the generic procedural modelling capabilities of Houdini with the architecture-specific procedural modeling language of CityEngine.
 
-## Build Instructions
+## Documentation
 
-### Preparation
-1. ```git clone git@github.com:Esri/houdini-cityengine-plugin.git && cd houdini-cityengine-plugin```
-1. fetch CityEngine SDK: ```cd conan/cesdk && conan create cesdk/1.9.3786@esri-rd-zurich/stable -s compiler=gcc -s compiler.version=4.8```
-1. package Houdini (adjust XXX and YYY): ```cd conan/houdini && conan create houdini/16.0.XXX@sidefx/stable -s compiler=gcc -s compiler.version=4.8 -o houdini-flavor=YYY```
-1. in the ```conanfile.txt``` adjust ```houdini-flavor``` to your houdini (apprentice, indie, core, fx)
+* [Quick Start](doc/USAGE.md)
+* [Building Palladio](doc/BUILD.md)
+* [ChangeLog](doc/CHANGELOG.md)
 
-### Building
-1. ```mkdir -p build/release && cd build/release```
-1. ```conan install ../../src```
-1. ```cmake -DCMAKE_BUILD_TYPE=Release ../../src```
-1. ```make install``` (the plugin is installed into your ~/houdini16/dso directory)
+External documentation:
+* [CityEngine Tutorials](http://desktop.arcgis.com/en/cityengine/latest/tutorials/introduction-to-the-cityengine-tutorials.htm)
+* [CityEngine CGA Reference](http://desktop.arcgis.com/en/cityengine/latest/cga/cityengine-cga-introduction.htm)
+* [CityEngine SDK API Reference](https://esri.github.io/esri-cityengine-sdk/html/index.html)
+* [Houdini 16.0 HDK Reference](http://www.sidefx.com/docs/hdk16.0/)  
 
-### Running
-1. ```LD_LIBRARY_PATH=/opt/hfs16.0.XXX/dsolib happrentice``` (or your houdini flavor)
+## Community
 
+Palladio is maintained as an open-source project by Matthias Buehler (vrbn.io) and Simon Haegler (Esri R&D Zurich). Matthias is focusing on UX/UI topics and use-cases in Urban Planning, while Simon is focusing on the implementation and procedural modelling technology.
 
-## Environment Variables
+Our goal is to bring as many Houdini and CityEngine users and developers on board as possible. Anyone is invited to fork and contribute to this project.
 
-- CITYENGINE_LOG_LEVEL: controls global (minimal) log level for all assign and generate nodes. valid values are "debug", "info", "warning", "error", "fatal"
-- CITYENGINE_LICENSE_SERVER: specify how CityEngine license is acquired. an empty string specifies a node-locked license while "<port>@<host>" indicates a network license server, e.g. "27000@my.server.org".
+## History
+
+Palladio has been invented by Matthias Buehler and Simon Haegler in early 2015 as part of an experiment to test out the CityEngine SDK APIs and to see if Houdini and CityEngine could be integrated more tightly than just via file-based import/export. Early results were promising and we were slowly cooking the project to v1.0 and took the decision to open-source it.
+
+
+## Licensing
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this work except in compliance with the License.
+You may obtain a copy of the License at
+
+> http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

doc/BUILD.md

@@ -0,0 +1,31 @@
+# Palladio
+
+## Build Requirements
+- [SideFX Houdini 16.0.x](https://sidefx.com/download) (apprentice edition is supported)
+- [Esri CityEngine 2017.1 or later](http://www.esri.com/software/cityengine) with node-locked license
+- RHEL 6/7 (or compatible) with GCC 4.8 (devtoolset 4.1)
+- [cmake 3.8 or later](https://cmake.org/download)
+- [conan 1.0.1 or later](https://www.conan.io/downloads)
+
+## Build Instructions
+
+### Bootstrap Dependencies
+This section is only needed once (or if you want to upgrade one of the dependencies).
+1. ```git clone git@github.com:esri/palladio.git && cd palladio```
+1. fetch CityEngine SDK: ```cd conan/cesdk && conan create cesdk/1.9.3786@esri-rd-zurich/stable -s compiler=gcc -s compiler.version=4.8```
+1. package Houdini (adjust XXX and YYY): ```cd conan/houdini && conan create houdini/16.0.XXX@sidefx/stable -s compiler=gcc -s compiler.version=4.8 -o houdini-flavor=YYY```
+1. in ```src/conanfile.txt``` adjust ```houdini-flavor``` to your houdini (apprentice, indie, core, fx)
+
+### Building
+1. ```mkdir -p build/release && cd build/release```
+1. ```conan install ../../src```
+1. ```cmake -DCMAKE_BUILD_TYPE=Release ../../src```
+1. ```make install``` (the plugin is installed into your ~/houdiniXXX/dso directory)
+
+### Running
+1. ```LD_LIBRARY_PATH=/opt/hfs16.0.XXX/dsolib happrentice``` (or your houdini flavor)
+
+## Environment Variables
+
+- CITYENGINE_LOG_LEVEL: controls global (minimal) log level for all assign and generate nodes. valid values are "debug", "info", "warning", "error", "fatal"
+- CITYENGINE_LICENSE_SERVER: specify how CityEngine license is acquired. an empty string specifies a node-locked license while "<port>@<host>" indicates a network license server, e.g. "27000@my.server.org".

doc/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Palladio ChangeLog
+
+## v1.0 (Jan 26, 2018)
+* Renamed project to "Palladio" (#68).
+* Updated documentation (#38).
+
+## v0.9 (Jan 18, 2018)
+* Add support for writing out primitive attributes from rule/generic CGA attributes (#40).
+* Removed random seed parameter UI, read it from incoming primitive attributes instead. Added centroid-based random seed as fallback.
+* Correctly update assign node parameters from RPK (#62).
+* Make primitive group creation optional and based on primitive classifier (#67).
+* Add support for CityEngine network licensing (#41).
+* Fixed crash when handling invalid RPK paths.
+* Remove style prefix on primitive attribute names.
+
+## v0.8 (Dec 19, 2017)
+* Added support for multiple UV sets (#36).
+* Added support for CGA reports (#39).
+* Properly use Houdini input mesh connectivity (make CGA operation "isClosedSurface" work correctly) (#49).
+* Refactored assign node to correctly use incoming geometry to evaluate default rule attribute values.
+
+## v0.7.1 (Nov 27, 2017)
+* Proper support for UVs and material attributes.
+* Introduced Conan to handle 3rd party packages in the build system (Houdini, CityEngine).
+* Updated to CityEngine SDK 2017.1 (CE SDK 1.9).
+
+## v0.7 (Sep 19, 2017)
+* Split plugin into two SOPs ("assign" and "generate") to support proper evaluation of rule attribute default values.
+* Abandoned rule param UI, purely rely on Houdini attribute tools (e.g. "AttributeCreate") to create/modify rule attributes (= no need for complicated UI on assign node).
+* Updated to Houdini 16 and CityEngine 2017.
+* Dropped Windows/macOS support temporarily.
+
+## v0.6 (Mar 15, 2016)
+* Support for rule attribute UI via Houdini multi-parameter.
+* Experimental support for Windows/macOS.
+* Updated to Houdini 15 and CityEngine 2016.
+
+## v0.4 (Oct 22, 2015)
+* Working geometry generation from CityEngine rule packages
+* Support to read rule attributes from primitive attributes
+* Implemented rule execution as single surface operator (SOP).
+* Updated to Houdini 13 and CityEngine 2015.
+
+## v0.1 - v0.3 (Spring 2015)
+* Early experiments with Houdini 12 and CityEngine 2014.

doc/USAGE.md

@@ -0,0 +1,72 @@
+# Palladio Quick Start
+
+## Prerequisites
+* Installation of Houdini 16.0.x
+* Installation of CityEngine 2017.x
+
+## Execute a simple CityEngine Rule
+
+1. Verify that Palladio is installed and all necessary files are present in ``$HOME/houdiniXX/dso``:
+
+    ![](img/installation01.png)
+1. In CityEngine, create the following rule file and share it as a rule package (RPK) to disk somewhere:
+   ```
+   attr height = 1
+   
+   @StartRule
+   Init -->
+      extrude(height)
+   ```
+1. Start Houdini in a bash console:
+    ```
+    LD_LIBRARY_PATH=/opt/hfs16.0/dsolib /opt/hfs16.0/bin/houdini
+    ```
+    (Use ``happrentice`` instead of ``houdini``, if you don't have a commercial license. You might want to create a ``start-houdini`` script or alias with this line.)
+1. In a new scene, add a ``grid`` node.
+1. Enter the ``grid`` node and add the two Palladio nodes ``pldAssign`` and ``pldGenerate``. Connect them like this: ![](img/extrude01.png)
+1. In the ``pldAssign`` node, set the ``Rule Package`` parameter to the path of the previously exported RPK.
+1. Make the ``pldGenerate`` node the active render node, this will trigger a "cooking" of the assign and generate nodes and execute the CityEngine Rule. You should now see an extruded grid: ![](img/extrude02.png)
+
+## Overriding Rule Attributes
+
+In the previous section we've used the default value for the ``height`` attribute. Let's use Houdini tools to modify the rule attribute prior to execution.
+
+1. Right click on the ``pldAssign`` node and bring up the spreadsheet view. Observe how the ``height`` primitive parameter is set to 1 for all primitives. This is the rule attribute default value and we're going to override it now. ![](img/attribute01.png)
+1. Add an ``AttributeCreate`` node between ``pldAssign`` and ``pldGenerate``.
+1. Set the attribute name to ``height`` and the ``Class`` to ``Primitive``. The extrusion vanishes because the default value is 0.
+1. Increase the value for ``height`` to see an actual extrusion: ![](img/attribute02.png)
+
+## Working with Material Attributes
+
+In this section, we are going to connect a material attribute generated by ``pldGenerate`` with a Mantra shader.
+
+1. Extend the rule from the first section with a ``color`` statement:
+    ```
+    attr height = 1
+
+    @StartRule
+    Init -->
+       color(1,0,0)
+       extrude(height)
+    ```
+    ![](img/materials01.png) 
+1. In Houdini, select the ``pldGenerate`` node and check the ``Emit material attributes`` check box. Open the spreadsheet to observe a number of material primitive attributes now being emitted by ``pldGenerate``.
+1. Add a ``Material`` node and connect it to the ``pldGenerate`` node. Make it the active render node:
+    
+    ![](img/materials02.png)
+1. In the ``Material Palette``, create a new ``Principled Shader`` instance and call it ``CityEngineShader``:
+
+    ![](img/materials03.png)
+1. Enter the ``CityEngineShader`` node and connect a ``Parameter`` node to the ``Surface/basecolor`` input:
+
+    ![](img/materials04.png) 
+
+1. Set the name of the ``Parameter`` node to ``color`` and also set the type to ``Color``. This name will match the primitive attribute emitted by ``pldGenerate``.
+
+    ![](img/materials05.png)
+
+1. Back in the network of the ``grid`` node, select the ``Material`` node and select ``/mat/CityEngineShader`` for the ``Material`` parameter.
+
+1. Hit Mantra render and you should see a red box in the render view.
+
+    ![](img/materials06.png)