RUIC 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 8266ac3944df4da06963ce797c9f7c4ded165e35
4
- data.tar.gz: 56f345f5e38f79cbc2ec24d13c3b591d88332bc3
3
+ metadata.gz: 8c4e1cec982987968c63ecbbafff9d3e411cde33
4
+ data.tar.gz: 12b6241b55467219a87ebdbe18b31a7a9c323cf2
5
5
  SHA512:
6
- metadata.gz: 324c07f70d84f98023a3b2de1606c5e91f158ec2fe13758028dabc71b7eae949253e34a579234bec5444f4aa4f35661ff603a3d88c463c9c75f2c1dc6e2383e5
7
- data.tar.gz: 7f3b3bbc26be7a229f2f7dfb180b05a0409b56dd7ff6418cd4e6f4c184b5e55bad8ddc433815b3c9eb2f59013934c67812eeb0be3d2225f64952d0430fba04ba
6
+ metadata.gz: c16621f5aefc0467c4ebb18df1a76addf920001033127b920a5504b2227bfd88d63abfde631580371cefd6b1551a672117ecb9f5e05c4178ff6652533bb83299
7
+ data.tar.gz: b50269750f9bbecd3e94f19662c4e1c3897f8e2e00c24aaf01b2a0af29affc6ec6325ac264664fd159f03393d0de8fd42453338c21b10ccdebddf2dcd61491ea
data/README.md CHANGED
@@ -1,207 +1,252 @@
1
- # What is RUIC?
2
- RUIC is a Ruby API for reading, analyzing, and manipulating application assets created by NVIDIA's [UI Composer][1]. Among other things, it allows you to:
3
-
4
- * See if an application is missing any assets (e.g. images or meshes) and what parts of the application are looking for those.
5
- * See if there are any files in the application folder that you can delete (e.g. images or materials that are no longer being used).
6
- * Read and modify the attributes of elements on different slides.
7
- * Batch change attributes (e.g. change all usage of one font or color to another).
8
- * Procedurally generate many models with automated placement in your scene.
9
-
10
- _Some of the features above are planned, but not yet implemented; see Known Limitations below._
11
-
12
- ## Table of Contents
13
- * [Installing RUIC](#installing-ruic)
14
- * [Using the RUIC DSL](#using-the-ruic-dsl)
15
- * [Creating and Accessing Applications](#creating-and-accessing-applications)
16
- * [Working with Presentations](#working-with-presentations)
17
- * [Finding Many Assets](#finding-many-assets)
18
- * [Working with References](#working-with-references)
19
- * [Writing Assertions](#writing-assertions)
20
- * [Locating MetaData.xml](#locating-metadataxml)
21
- * [Known Limitations (aka TODO)](#known-limitations-aka-todo)
22
- * [History](#history)
23
- * [License & Contact](#license--contact)
24
-
25
-
26
-
27
- # Installing RUIC
28
- RUIC can be installed via RubyGems (part of Ruby) via the command:
29
-
30
- gem install ruic # May need `sudo gem install ruic` depending on your setup
31
-
32
- Although RUIC is a pure-Ruby library, it relies on [Nokogiri][2] for all the XML processing and manipulation. Installing RUIC will also automatically install Nokogiri, which may require some compilation.
33
-
34
-
35
-
36
- # Using the RUIC DSL
37
-
38
- RUIC scripts are pure Ruby with a few convenience methods added. You run them via the `ruic` command-line script, e.g.
39
-
40
- ruic myscript.ruic # or .rb extension, for syntax highlighting while editing
41
-
42
-
43
- ## Creating and Accessing Applications
44
- RUIC scripts must start with `uia` commands to load an application and all its assets.
45
- After this you can access the application as `app`:
46
-
47
- ```ruby
48
- uia '../MyApp.uia' # Relative to the ruic script file, or absolute
49
-
50
- show app.file #=> /var/projects/UIC/MyApp/main/MyApp.uia
51
- show app.filename #=> MyApp.uia
52
-
53
- show app.assets.count #=> 7
54
- # You can ask for app.behaviors, app.presentations, app.statemachines, and app.renderplugins
55
- # for arrays of specific asset types
56
- ```
57
-
58
- _The `show` command prints the result; it is simply a nicer alias for `puts`._
59
-
60
- If you need to load multiple applications in the same script, subsequent `uia` commands will create
61
- `app2`, `app3`, etc. for you to use.
62
-
63
- ```ruby
64
- uia '../MyApp.uia' # Available as 'app'
65
- uia '../../v1/MyApp.uia' # Available as 'app2'
66
- ```
67
-
68
-
69
- ## Working with Presentations
70
-
71
- ```ruby
72
- uia '../MyApp.uia'
73
-
74
- main = app.main_presentation # The presentation displayed as the main presentation (regardless of id)
75
- sub = app['#nav'] # You can ask for an asset based on the id in the .uia...
76
- sub = app['Navigation.uip'] # or based on the path to the file (relative to the .uia)
77
-
78
-
79
- car = sub/"Scene.Vehicle.Group.Car" # Find elements in a presentation by presentation path…
80
- car = app/"nav:Scene.Vehicle.Group.Car" # …or absolute application path
81
-
82
- show car.name #=> Car
83
- show car.type #=> Model # Scene, Layer, Camera, Light, Group, Model, Material,
84
- # Image, Behavior, Effect, ReferencedMaterial, Text,
85
- # RenderPlugin, Component, (custom materials)
86
-
87
- show car.component? #=> false # Ask if an element is a component
88
- assert car.component==sub.scene # Ask for the owning component; may be the scene
89
- ```
90
-
91
- ## Finding Many Assets
92
-
93
- ```ruby
94
- uia 'MyApp.uia'
95
- main = app.main_presentation
96
-
97
- every_asset = main.find # Array of matching assets
98
- master_assets = main.find master:true # Test for master/nonmaster
99
- models = main.find type:'Model' # …or based on type
100
- gamecovers = main.find name:'Game Cover' # …or based on name
101
- slide2_assets = main.find slide:2 # …or presence on slide
102
- rectangles = main.find attributes:{sourcepath:'#Rectangle'} # …or attribute values
103
-
104
- # Combine tests to get more specific
105
- master_models = main.find type:'Model', master:true
106
- slide2_rects = main.find type:'Model', slide:2, attributes:{sourcepath:'#Rectangle'}
107
- nonmaster_s2 = main.find slide:2, master:false
108
- red_materials = main.find type:'Material', attributes:{ diffuse:[1,0,0] }
109
-
110
- # You can match values more loosely
111
- pistons = main.find name:/^Piston/ # Regex for batch finding
112
- bottom_row = main.find attributes:{position:[nil,-200,nil]} # nil for wildcards
113
-
114
- # Restrict the search to a sub-tree
115
- group = main/"Scene.Layer.Group"
116
- group_models = group.find type:'Model' # Original asset is never included
117
- group_models = main.find under:group, type:'Model' # Or use `under` for sub-tree
118
-
119
- # Iterate the results as they are found
120
- main.find type:'Model', name:/^Piston/ do |model, index| # Using the index is optional
121
- show "Model #{index} is named #{model.name}"
122
- end
123
- ```
124
-
125
- Notes:
126
- * `nil` inside an array is a "wildcard" value, allowing you to test only specific values
127
- * Numbers (both in vectors/colors/rotations and float/long values) must only be within `0.001` to match.
128
- * _For example, `attributes:{diffuse:[1,0,0]}` will match a color with `diffuse=".9997 0.0003 0"`_
129
- * Results of `find` are always in scene-graph order.
130
-
131
-
132
- ## Working with References
133
-
134
- ```ruby
135
- uia 'MyApp.uia'
136
- mat1 = app/"main:Scene.Layer.Sphere.Material" # A normal UIC Material
137
- mat2 = app/"main:Scene.Layer.Cube.Material" # A normal UIC Material
138
- p mat2.type #=> "Material"
139
- ref = mat2.replace_with_referenced_material # A very specific method :)
140
- p ref.properties['referencedmaterial'].type #=> "ObjectRef"
141
- p ref['referencedmaterial',0].object #=> nil
142
- p ref['referencedmaterial',0].type #=> :absolute
143
- ref['referencedmaterial',0].object = mat1 #=> Sets an absolute reference
144
- ref['referencedmaterial',0].type = :path #=> Use a relative path instead
145
-
146
- # Alternatively, you can omit the .object when setting the reference:
147
- # ref['referencedmaterial',0] = mat1
148
-
149
- mat3 = ref['referencedmaterial',1].object #=> Get the asset pointed to
150
- assert mat1 == mat3 #=> They are the same! It worked!
151
-
152
- app.save_all! #=> Write presentations in place
153
- ```
154
-
155
- ## Writing Assertions
156
-
157
-
158
- ## Locating MetaData.xml
159
- RUIC needs access to a UIC `MetaData.xml` file to understand the properties in the various XML files.
160
- By default RUIC will look in the location specified by `RUIC::DEFAULTMETADATA`, e.g.
161
- `C:/Program Files (x86)/NVIDIA Corporation/UI Composer 8.0/res/DataModelMetadata/en-us/MetaData.xml`
162
-
163
- If this file is in another location, you can tell the script where to find it either:
164
-
165
- * on the command line: `ruic -m path/to/MetaData.xml myscript.ruic`
166
- * in your ruic script: `metadata 'path/to/MetaData.xml' # before any 'app' commands`
167
-
168
-
169
-
170
- # Known Limitations (aka TODO)
171
- _In decreasing priority…_
172
-
173
- - Report on image assets, their sizes
174
- - Report used assets (and where they are used)
175
- - Report unused assets (in a format suitable for automated destruction)
176
- - Report missing assets (and who was looking for them)
177
- - Gobs more unit tests
178
- - Parse .lua headers (in case one references an image)
179
- - Parse render plugins
180
- - Read/edit animation tracks
181
- - Find all colors, and where they are used
182
- - Visual actions for State Machines
183
- - Create new presentation assets (e.g. add a new sphere)
184
- - Modify the scene graph of presentations
185
- - Create new presentations/applications from code
186
- - Report on image asset file formats (e.g. find PNGs, find DXT1 vs DXT3 vs DXT Luminance…)
187
-
188
-
189
- # History
190
-
191
- ## v0.0.1 - 2014-Nov-7
192
- * Initial gem release
193
- * Crawl presentations and modify attributes
194
- * Batch find assets
195
- * Save presentation changes back to disk
196
-
197
-
198
-
199
- # License & Contact
200
- RUIC is copyright ©2014 by Gavin Kistner and is licensed under the [MIT License][3]. See the `LICENSE` file for more details.
201
-
202
- For bugs or feature requests please open [issues on GitHub][4]. For other communication you can [email the author directly](mailto:!@phrogz.net?subject=RUIC).
203
-
204
- [1]: http://uicomposer.nvidia.com
205
- [2]: http://nokogiri.org
206
- [3]: http://opensource.org/licenses/MIT
207
- [4]: https://github.com/Phrogz/RUIC/issues
1
+ # What is RUIC?
2
+ RUIC is a Ruby API for reading, analyzing, and manipulating application assets created by NVIDIA's [UI Composer][1]. Among other things, it allows you to:
3
+
4
+ * See if an application is missing any assets (e.g. images or meshes) and what parts of the application are looking for those.
5
+ * See if there are any files in the application folder that you can delete (e.g. images or materials that are no longer being used).
6
+ * Read and modify the attributes of elements on different slides.
7
+ * Batch change attributes (e.g. change all usage of one font or color to another).
8
+ * Procedurally generate many models with automated placement in your scene.
9
+
10
+ _Some of the features above are planned, but not yet implemented; see Known Limitations below._
11
+
12
+ ## Table of Contents
13
+ * [Installing RUIC](#installing-ruic)
14
+ * [Using the RUIC DSL](#using-the-ruic-dsl)
15
+ * [Creating and Accessing Applications](#creating-and-accessing-applications)
16
+ * [Working with Presentations](#working-with-presentations)
17
+ * [Finding Many Assets](#finding-many-assets)
18
+ * [Working with References](#working-with-references)
19
+ * [Writing Assertions](#writing-assertions)
20
+ * [Locating MetaData.xml](#locating-metadataxml)
21
+ * [Interactive RUIC](#interactive-ruic)
22
+ * [Known Limitations (aka TODO)](#known-limitations-aka-todo)
23
+ * [History](#history)
24
+ * [License & Contact](#license--contact)
25
+
26
+
27
+
28
+ # Installing RUIC
29
+ RUIC can be installed via RubyGems (part of Ruby) via the command:
30
+
31
+ gem install ruic # May need `sudo gem install ruic` depending on your setup
32
+
33
+ Although RUIC is a pure-Ruby library, it relies on [Nokogiri][2] for all the XML processing and manipulation. Installing RUIC will also automatically install Nokogiri, which may require some compilation.
34
+
35
+
36
+
37
+ # Using the RUIC DSL
38
+
39
+ RUIC scripts are pure Ruby with a few convenience methods added. You run them via the `ruic` command-line script, e.g.
40
+
41
+ ruic myscript.ruic # or .rb extension, for syntax highlighting while editing
42
+
43
+
44
+ ## Creating and Accessing Applications
45
+ RUIC scripts must start with `uia` commands to load an application and all its assets.
46
+ After this you can access the application as `app`:
47
+
48
+ ```ruby
49
+ uia '../MyApp.uia' # Relative to the ruic script file, or absolute
50
+
51
+ show app.file #=> /var/projects/UIC/MyApp/main/MyApp.uia
52
+ show app.filename #=> MyApp.uia
53
+
54
+ show app.assets.count #=> 7
55
+ # You can ask for app.behaviors, app.presentations, app.statemachines, and app.renderplugins
56
+ # for arrays of specific asset types
57
+ ```
58
+
59
+ _The `show` command prints the result; it is simply a nicer alias for `puts`._
60
+
61
+ If you need to load multiple applications in the same script, subsequent `uia` commands will create
62
+ `app2`, `app3`, etc. for you to use.
63
+
64
+ ```ruby
65
+ uia '../MyApp.uia' # Available as 'app'
66
+ uia '../../v1/MyApp.uia' # Available as 'app2'
67
+ ```
68
+
69
+
70
+ ## Working with Presentations
71
+
72
+ ```ruby
73
+ uia '../MyApp.uia'
74
+
75
+ main = app.main_presentation # The presentation displayed as the main presentation (regardless of id)
76
+ sub = app['#nav'] # You can ask for an asset based on the id in the .uia...
77
+ sub = app['Navigation.uip'] # or based on the path to the file (relative to the .uia)
78
+
79
+
80
+ car = sub/"Scene.Vehicle.Group.Car" # Find elements in a presentation by presentation path
81
+ car = app/"nav:Scene.Vehicle.Group.Car" # …or absolute application path
82
+
83
+ show car.name #=> Car
84
+ show car.type #=> Model # Scene, Layer, Camera, Light, Group, Model, Material,
85
+ # Image, Behavior, Effect, ReferencedMaterial, Text,
86
+ # RenderPlugin, Component, (custom materials)
87
+
88
+ show car.component? #=> false # Ask if an element is a component
89
+ assert car.component==sub.scene # Ask for the owning component; may be the scene
90
+ ```
91
+
92
+ ## Finding Many Assets
93
+
94
+ ```ruby
95
+ uia 'MyApp.uia'
96
+ main = app.main_presentation
97
+
98
+ every_asset = main.find # Array of matching assets
99
+ master_assets = main.find master:true # Test for master/nonmaster
100
+ models = main.find type:'Model' # …or based on type
101
+ gamecovers = main.find name:'Game Cover' # …or based on name
102
+ slide2_assets = main.find slide:2 # …or presence on slide
103
+ rectangles = main.find attributes:{sourcepath:'#Rectangle'} # …or attribute values
104
+
105
+ # Combine tests to get more specific
106
+ master_models = main.find type:'Model', master:true
107
+ slide2_rects = main.find type:'Model', slide:2, attributes:{sourcepath:'#Rectangle'}
108
+ nonmaster_s2 = main.find slide:2, master:false
109
+ red_materials = main.find type:'Material', attributes:{ diffuse:[1,0,0] }
110
+
111
+ # You can match values more loosely
112
+ pistons = main.find name:/^Piston/ # Regex for batch finding
113
+ bottom_row = main.find attributes:{position:[nil,-200,nil]} # nil for wildcards
114
+
115
+ # Restrict the search to a sub-tree
116
+ group = main/"Scene.Layer.Group"
117
+ group_models = group.find type:'Model' # Original asset is never included
118
+ group_models = main.find under:group, type:'Model' # Or use `under` for sub-tree
119
+
120
+ # Iterate the results as they are found
121
+ main.find type:'Model', name:/^Piston/ do |model, index| # Using the index is optional
122
+ show "Model #{index} is named #{model.name}"
123
+ end
124
+ ```
125
+
126
+ Notes:
127
+ * `nil` inside an array is a "wildcard" value, allowing you to test only specific values
128
+ * Numbers (both in vectors/colors/rotations and float/long values) must only be within `0.001` to match.
129
+ * _For example, `attributes:{diffuse:[1,0,0]}` will match a color with `diffuse=".9997 0.0003 0"`_
130
+ * Results of `find` are always in scene-graph order.
131
+
132
+
133
+ ## Working with References
134
+
135
+ ```ruby
136
+ uia 'MyApp.uia'
137
+ mat1 = app/"main:Scene.Layer.Sphere.Material" # A normal UIC Material
138
+ mat2 = app/"main:Scene.Layer.Cube.Material" # A normal UIC Material
139
+ p mat2.type #=> "Material"
140
+ ref = mat2.replace_with_referenced_material # A very specific method :)
141
+ p ref.properties['referencedmaterial'].type #=> "ObjectRef"
142
+ p ref['referencedmaterial',0].object #=> nil
143
+ p ref['referencedmaterial',0].type #=> :absolute
144
+ ref['referencedmaterial',0].object = mat1 #=> Sets an absolute reference
145
+ ref['referencedmaterial',0].type = :path #=> Use a relative path instead
146
+
147
+ # Alternatively, you can omit the .object when setting the reference:
148
+ # ref['referencedmaterial',0] = mat1
149
+
150
+ mat3 = ref['referencedmaterial',1].object #=> Get the asset pointed to
151
+ assert mat1 == mat3 #=> They are the same! It worked!
152
+
153
+ app.save_all! #=> Write presentations in place
154
+ ```
155
+
156
+ ## Writing Assertions
157
+
158
+
159
+ ## Locating MetaData.xml
160
+ RUIC needs access to a UIC `MetaData.xml` file to understand the properties in the various XML files.
161
+ By default RUIC will look in the location specified by `RUIC::DEFAULTMETADATA`, e.g.
162
+ `C:/Program Files (x86)/NVIDIA Corporation/UI Composer 8.0/res/DataModelMetadata/en-us/MetaData.xml`
163
+
164
+ If this file is in another location, you can tell the script where to find it either:
165
+
166
+ * on the command line: `ruic -m path/to/MetaData.xml myscript.ruic`
167
+ * in your ruic script: `metadata 'path/to/MetaData.xml' # before any 'app' commands`
168
+
169
+
170
+ # Interactive RUIC
171
+ In addition to executing a standalone script, RUIC also has a REPL (like IRB) that allows you to
172
+ interactively execute and test changes to your application/presentations before saving.
173
+ There are two ways to enter interactive mode:
174
+
175
+ * If you invoke the `ruic` binary with a `.uia` file as the argument the interpreter will load
176
+ the application and enter the REPL:
177
+ ```
178
+ $ ruic myapp.uia
179
+ (RUIC v0.2.2 interactive session; 'quit' or ctrl-d to end)
180
+
181
+ uia "test/projects/SimpleScene/SimpleScene.uia"
182
+ #=> <UIC::Application 'SimpleScene.uia'>
183
+ ```
184
+
185
+ * Alternatively, you can have RUIC execute a script and then enter the interactive REPL
186
+ by supplying the `-i` command-line switch:
187
+ ```
188
+ $ ruic -i test/referencematerials.ruic
189
+ (RUIC v0.2.2 interactive session; 'quit' or ctrl-d to end)
190
+
191
+ app
192
+ #=> <UIC::Application 'ReferencedMaterials.uia'>
193
+
194
+ cubemat
195
+ #=> <asset Material#Material_002>
196
+ ```
197
+ As shown above, all local variables created by the script continue to be available
198
+ in the interactive session.
199
+
200
+
201
+ # Known Limitations (aka TODO)
202
+ _In decreasing priority…_
203
+
204
+ - Report on image assets, their sizes
205
+ - Report used assets (and where they are used)
206
+ - Report unused assets (in a format suitable for automated destruction)
207
+ - Report missing assets (and who was looking for them)
208
+ - Gobs more unit tests
209
+ - Parse .lua headers (in case one references an image)
210
+ - Parse render plugins
211
+ - Read/edit animation tracks
212
+ - Find all colors, and where they are used
213
+ - Visual actions for State Machines
214
+ - Create new presentation assets (e.g. add a new sphere)
215
+ - Modify the scene graph of presentations
216
+ - Create new presentations/applications from code
217
+ - Report on image asset file formats (e.g. find PNGs, find DXT1 vs DXT3 vs DXT Luminance…)
218
+
219
+
220
+ # History
221
+
222
+ ## v0.2.2 - 2014-Nov-7
223
+ * REPL shows version number when it starts
224
+
225
+ ## v0.2.1 - 2014-Nov-7
226
+ * REPL mode after script maintains binding of script (all local variables remain available)
227
+ * Customized `.irbrc` files will not cause warnings.
228
+
229
+ ## v0.2.0 - 2014-Nov-7
230
+ * Add Presentation#save_as
231
+ * REPL working directory is same as .uia
232
+
233
+ ## v0.1.0 - 2014-Nov-7
234
+ * Add REPL mode for ruic binary
235
+
236
+ ## v0.0.1 - 2014-Nov-7
237
+ * Initial gem release
238
+ * Crawl presentations and modify attributes
239
+ * Batch find assets
240
+ * Save presentation changes back to disk
241
+
242
+
243
+
244
+ # License & Contact
245
+ RUIC is copyright ©2014 by Gavin Kistner and is licensed under the [MIT License][3]. See the `LICENSE` file for more details.
246
+
247
+ For bugs or feature requests please open [issues on GitHub][4]. For other communication you can [email the author directly](mailto:!@phrogz.net?subject=RUIC).
248
+
249
+ [1]: http://uicomposer.nvidia.com
250
+ [2]: http://nokogiri.org
251
+ [3]: http://opensource.org/licenses/MIT
252
+ [4]: https://github.com/Phrogz/RUIC/issues