RUIC 0.0.1 → 0.1.0

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: 9cedef554fe79e1c76d028914357e410a7199799
4
- data.tar.gz: 7462e76fe72621bb0985000630edea4daed2148c
3
+ metadata.gz: 701fc8ed1b3b80439288e9aff34936285aa24210
4
+ data.tar.gz: f8373806b048154b3869515c911153721c483dac
5
5
  SHA512:
6
- metadata.gz: 340ca92ab34bcccce9605db54071ff11ad20294e6f9421a5e260bcfd5215574ece125f277a9f8d896a120d1dbcf8002e7c7521ecd3aa17e7ff40205729f313a3
7
- data.tar.gz: 3eb97d8bafb8b1291929b7e34c6417316a472d313b189985057c892642c468395067bdbfa77ce2850c78a8dffbd1596fc3fff66a7d9e6f6ab1b74d0c1012ca9e
6
+ metadata.gz: 084df33530afad35f3ab412300b0cd79504154e7dc07d565319b09dc395d42a93793528986ae53d7a3e91d8d79cf9130dcdac061d8fce48df749f0ca9dd8cded
7
+ data.tar.gz: 7619b5c097ed8b05275b2a57f6b1d0c90d90fd79789f621476227f3903ff27336786a6f9e169e3030767c94988cfc44687c08c24637a2ba6740468992bd20598
data/README.md CHANGED
@@ -1,201 +1,207 @@
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 # Returns an array of matching assets
98
- master_assets = main.find master:true # Test for master/non-master
99
- models = main.find type:'Model' # Test based on type
100
- slide2_assets = main.find slide:2 # Test based on slide presence
101
- rectangles = main.find attributes:{sourcepath:'#Rectangle'} # Test based on attribute values
102
- master_models = main.find type:'Model', master:true # Combine any tests
103
- slide2_rects = main.find type:'Model', slide:2, attributes:{sourcepath:'#Rectangle'}
104
- gamecovers = main.find name:'Game Cover'
105
- pistons = main.find name:/^Piston/ # Regexes allow easy batch finding
106
- bottom_row = main.find attributes:{position:[nil,-200,nil]}
107
- red_materials = main.find type:'Material', attributes:{diffuse:[1,0,0] }
108
-
109
- # Restricting the search to a sub-tree
110
- group = main/"Scene.Layer.Group"
111
- group_models = group.find type:'Model' # Original asset is never in the results
112
- group_models = main.find under:group, type:'Model' # Alternative sub-tree limit using `under`
113
-
114
- # Iterate the results as they are found
115
- main.find type:'Model', name:/^Piston/ do |model, index|
116
- show "Model #{index} is named #{model.name}"
117
- end
118
- ```
119
-
120
- Notes:
121
- * `nil` inside an array is a "wildcard" value, allowing you to test only specific values
122
- * Numbers (both in vectors/colors/rotations and float/long values) must only be within `0.001` to match.
123
- * _For example, `attributes:{diffuse:[1,0,0]}` will match a color with `diffuse=".9997 0.0003 0"`_
124
- * Results of `find` are always in scene-graph order.
125
-
126
-
127
- ## Working with References
128
-
129
- ```ruby
130
- uia 'MyApp.uia'
131
- mat1 = app/"main:Scene.Layer.Sphere.Material" # A normal UIC Material
132
- mat2 = app/"main:Scene.Layer.Cube.Material" # A normal UIC Material
133
- p mat2.type #=> "Material"
134
- ref = mat2.replace_with_referenced_material # A very specific method :)
135
- p ref.properties['referencedmaterial'].type #=> "ObjectRef"
136
- p ref['referencedmaterial',0].object #=> nil
137
- p ref['referencedmaterial',0].type #=> :absolute
138
- ref['referencedmaterial',0].object = mat1 #=> Sets an absolute reference
139
- ref['referencedmaterial',0].type = :path #=> Use a relative path instead
140
-
141
- # Alternatively, you can omit the .object when setting the reference:
142
- # ref['referencedmaterial',0] = mat1
143
-
144
- mat3 = ref['referencedmaterial',1].object #=> Get the asset pointed to
145
- assert mat1 == mat3 #=> They are the same! It worked!
146
-
147
- app.save_all! #=> Write presentations in place
148
- ```
149
-
150
- ## Writing Assertions
151
-
152
-
153
- ## Locating MetaData.xml
154
- RUIC needs access to a UIC `MetaData.xml` file to understand the properties in the various XML files.
155
- By default RUIC will look in the location specified by `RUIC::DEFAULTMETADATA`, e.g.
156
- `C:/Program Files (x86)/NVIDIA Corporation/UI Composer 8.0/res/DataModelMetadata/en-us/MetaData.xml`
157
-
158
- If this file is in another location, you can tell the script where to find it either:
159
-
160
- * on the command line: `ruic -m path/to/MetaData.xml myscript.ruic`
161
- * in your ruic script: `metadata 'path/to/MetaData.xml' # before any 'app' commands`
162
-
163
-
164
-
165
- # Known Limitations (aka TODO)
166
- _In decreasing priority…_
167
-
168
- - Report on image assets, their sizes
169
- - Report used assets (and where they are used)
170
- - Report unused assets (in a format suitable for automated destruction)
171
- - Report missing assets (and who was looking for them)
172
- - Gobs more unit tests
173
- - Parse .material files
174
- - Navigate through scene graph hierarchy (parent, children)
175
- - Parse .lua files (in case one references an image)
176
- - Parse render plugins
177
- - Read/edit animation tracks
178
- - Find all colors, and where they are used
179
- - Path to element
180
- - `element/'relative.path.resolving'`
181
- - Visual actions for State Machines
182
- - Create new presentation assets (e.g. add a new sphere)
183
- - Modify the scene graph of presentations
184
- - Create new presentations/applications from code
185
- - Report on image asset file formats (e.g. find PNGs, find DXT1 vs DXT3 vs DXT Luminance…)
186
-
187
-
188
- # History
189
- * _In development, no releases yet._
190
-
191
-
192
-
193
- # License & Contact
194
- RUIC is copyright ©2014 by Gavin Kistner and is licensed under the [MIT License][3]. See the `LICENSE` file for more details.
195
-
196
- 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).
197
-
198
- [1]: http://uicomposer.nvidia.com
199
- [2]: http://nokogiri.org
200
- [3]: http://opensource.org/licenses/MIT
201
- [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
+ * [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
data/bin/ruic CHANGED
@@ -9,15 +9,17 @@ end
9
9
 
10
10
  USAGE = <<ENDUSAGE
11
11
  Usage:
12
- ruic [-h] [-v] [-m /path/to/MetaData.xml] myscript.ruic
12
+ ruic [-h] [-v] [-i] [-m path/to/MetaData.xml] [-u path/to/my.uia] [myscript.ruic]
13
13
  ENDUSAGE
14
14
 
15
15
  HELP = <<ENDHELP
16
- -h, --help Show this help.
17
- -v, --version Show the version number (#{RUIC::VERSION}).
18
- -m, --metadata The path to use for MetaData.xml
19
- Default: #{RUIC::DEFAULTMETADATA}
20
- Will be overridden by any `metadata` call in your script.
16
+ -h, --help Show this help.
17
+ -v, --version Show the version number (#{RUIC::VERSION}).
18
+ -i, --interactive Enter an interactive REPL after running the script (if any).
19
+ -m, --metadata The path to use for MetaData.xml
20
+ Default: #{RUIC::DEFAULTMETADATA}
21
+ Will be overridden by any `metadata` call in your script.
22
+ -u, --uia An application to load.
21
23
  ENDHELP
22
24
 
23
25
  ARGS = {}
@@ -25,9 +27,11 @@ UNFLAGGED_ARGS = [ :script ]
25
27
  next_arg = UNFLAGGED_ARGS.first
26
28
  ARGV.each do |arg|
27
29
  case arg
28
- when '-h','--help' then ARGS[:help] = true
29
- when '-v','--version' then ARGS[:version] = true
30
- when '-m','--metadata' then next_arg = :meta
30
+ when '-h','--help' then ARGS[:help] = true
31
+ when '-v','--version' then ARGS[:version] = true
32
+ when '-i','--interactive' then ARGS[:interactive] = true
33
+ when '-m','--metadata' then next_arg = :meta
34
+ when '-u','--uia' then next_arg = :uia
31
35
  else
32
36
  if next_arg
33
37
  ARGS[next_arg] = arg
@@ -39,14 +43,18 @@ end
39
43
 
40
44
  puts "RUIC v#{RUIC::VERSION}" if ARGS[:version]
41
45
 
42
- if ARGS[:help] || !ARGS[:script]
43
- puts USAGE unless ARGS[:version]
44
- puts HELP if ARGS[:help]
45
- exit ARGS[:help] ? 0 : 1
46
+ if ARGS[:help]
47
+ puts USAGE, HELP
48
+ exit 0
46
49
  end
47
50
 
48
51
  if ARGS[:meta]
49
52
  RUIC::DEFAULTMETADATA.replace File.expand_path(ARGS[:meta])
50
53
  end
51
54
 
52
- RUIC(ARGS[:script])
55
+ if ARGS[:script] && File.extname(ARGS[:script])==".uia"
56
+ ARGS[:uia] = ARGS[:script]
57
+ ARGS[:script] = nil
58
+ end
59
+
60
+ RUIC script:ARGS[:script], uia:ARGS[:uia], repl:ARGS[:interactive] || !ARGS[:script]