Tutorial 12: Scripted report export

Size: px

Start display at page:

Download "Tutorial 12: Scripted report export"

Mervyn Baldwin
6 years ago
Views:

Tutorial 12: Scripted report export Download items Tutorial data Tutorial PDF This tutorial shows how to use CGA report variables in combination with the Python-based exporter.

3 Tutorial 12: Scripted report export Download items Tutorial data Tutorial PDF This tutorial shows how to use CGA report variables in combination with the Python-based exporter. We will report information of instances distributed in our scene, and use it to generate an instance map in a simple text file. More information on the CityEngine-specific Python command set can be found in the CityEngine help: Help > Help Contents > Manual > Python Scripting. Note: The Python Scripting Interface is not available in all CityEngine versions. Part 1: Report Information of Instanced Buildings In the first part, we will use an existing CGA file that distributes instanced buildings in our scene and add report variables to prepare additional information of the instances used for the Script Based Exporter in part 2. This tutorial requires a basic knowledge of CGA Shape Grammar as well as the basics of the Scripting API. Using the Script Based Exporter The Script Based Exporter is basically a CGA generation process that is triggered via export. The Python script that is set in the export settings and runs along the export/generation process can process each model during and after generation. In this example we are going to: Prepare CGA commands that report the required values. Query the values reported in CGA rules for each generated model. Write a text file with the collected report values after all models are generated. Goal We want to write out a text file that contains the necessary data to be able to load the distributed building instances in arbitrary followup applications. For every instance, the following values should be written: asset identifier position in 3 axes rotation in 3 axes scale in 3 axes In the following form: Copyright Esri. All rights reserved. 3

4 nr asset xpos xrot xscale 0 scifi_building_9.obj scifi_building_17.obj scifi_building_5.obj Tutorial Setup 1. Import the project Tutorial_12_Scripted_Report_Export into your CityEngine workspace. 2. Open scene Tutorial_12_Scripted_Report_Export/scenes/reportInstances_01.cej. Preparing a Generic Report Rule in an External CGA File Although we could add all the necessary reporting commands directly in the CGA file instance_city_01.cga, we will write an external CGA file with a generic reporting rule. This way, we will be able to use the reporting rule for arbitrary CGA files. 1. Create a new rule file File > New... > CityEngine > CGA Rule File. 2. And name it instancereporting.cga. Create a new rule InstanceReport. We need a rule parameter asset to be able to report the asset identifier. InstanceReport(asset) --> Reporting Transformation Data Asset Identifier We simply report the rule parameter asset. ## report asset identifier report("asset", asset) Scale In most cases one needs a scale relative to the original asset size. We therefore cannot report the scope size only, but need to divide it by the asset size. The original asset size can be queried using the assetinfo() command. assetinfo(asset, "sx") queries the size in x-axis. The report commands for the scale are therefore: ## report scale values relative to asset report("xscale", scope.sx/assetinfo(asset, "sx")) report("yscale", scope.sy/assetinfo(asset, "sy")) report("zscale", scope.sz/assetinfo(asset, "sz")) Rotation We want to report the rotation in world coordinates, and therefore need to convert the pivot rotation in CityEngine using the convert() command: ## report rotation in world coords report("xrot", convert(x, pivot, world, orient, 0,0,0)) report("yrot", convert(y, pivot, world, orient, 0,0,0)) report("zrot", convert(z, pivot, world, orient, 0,0,0)) Copyright Esri. All rights reserved. 4

Position Position is the trickiest part. To be able to instance your assets correctly in your follow-up application, it is crucial to pay attention to the pivot and the position of the used assets.

5 Position Position is the trickiest part. To be able to instance your assets correctly in your follow-up application, it is crucial to pay attention to the pivot and the position of the used assets. In our case the assets have their pivot in their center on the ground plane, and are located on the world origin. See the Maya screenshot below for clarification: Before reporting the position, we will therefore modify the asset scope in the following way: The scope is scaled to a small "needle", and centered in x and z. This way we make sure the reported position corresponds to the pivot of the asset in Maya. ## scale and center scope s(0.0001,'1,0.0001) center(xz) Again, the position needs to be converted to world coordinates: ## report position in world coords report("xpos", convert(x, scope, world, pos, 0,0,0)) report("ypos", convert(y, scope, world, pos, 0,0,0)) report("zpos", convert(z, scope, world, pos, 0,0,0)) We have now reported all the required values. To make sure no undesired geometry is displayed in the viewport, we add a NIL command to the end for the reporting rule. The final reporting rule: InstanceReport(asset) --> ## report instance ID report("asset", asset) ## report scale values relative to asset report("xscale", scope.sx/assetinfo(asset, "sx")) report("yscale", scope.sy/assetinfo(asset, "sy")) report("zscale", scope.sz/assetinfo(asset, "sz")) ## report rotation in world coords report("xrot", convert(x, pivot, world, orient, 0,0,0)) report("yrot", convert(y, pivot, world, orient, 0,0,0)) report("zrot", convert(z, pivot, world, orient, 0,0,0)) ## scale and center scope s(0.001,'1,0.001) center(xz) ## report position in world coords report("xpos", convert(x, scope, world, pos, 0,0,0)) report("ypos", convert(y, scope, world, pos, 0,0,0)) report("zpos", convert(z, scope, world, pos, 0,0,0)) NIL Copyright Esri. All rights reserved. 5

cga" Now we simply add the InstanceReport rule to the end of our building rule. Make sure to also add the leaf rule Asset. after the insert command to make sure the asset is generated.

6 Using the Report Rule Let's get back to our original CGA rule file and use the prepared report rule. At the beginning of the file instance_city_01.cga, add the following line to import the prepared report rule file with the id instancereporting. import instancereporting:"instancereporting.cga" Now we simply add the InstanceReport rule to the end of our building rule. Make sure to also add the leaf rule Asset. after the insert command to make sure the asset is generated. Building(asset) --> s('1,0,'1) i(asset) Asset. instancereporting.instancereport(asset) Generate a building now, and look into the Reports pane of the Inspector, which should look similar to this: Note: The Reports pane in the Inspector is only for statistical reports, and does not display all values (e.g. does not display strings). However, it can be used in our case to make sure all required values are reported. Part 2: The Export Script We will now process the prepared report data using the Script Based Exporter. For this, we need to create a new Python script which will do the job. Python Script Export Template 1. Create a new python export script from template File > New... > Python > Python Module. 2. Choose the project's script folder, name it exportinstances and choose Module: Export (Reporting) as template. The template script contains four functions. We only need finishmodel() and finishexport(), so delete the other two. Copyright Esri. All rights reserved. 6

7 Access Report Data in finishmodel() The array of report variables of the currently processed shape can be accessed in the following way: model.getreports()['asset'] Where asset is the name of the report variable. Because not all generated shapes have an instance on them (e.g. empty ground shapes or street shapes), we first need to check for the presence of report data using one of the report variables, namely 'asset': if(model.getreports().has_key('asset')): If you look at the CGA rules of the generated buildings in detail, you will notice that some shapes contain more than one instance. We therefore need to loop over all the reported datasets per shape by first getting the length of the 'asset' array. As a first test, we will print out the report data array to the console: l = len(model.getreports()['asset']) for i in range(0,l): print model.getreports() Running the Script-Based Exporter 1. Select a small set of buildings or lot shapes 2. Start the script based exporter: File > Export... > CityEngine > Export Models of selected Shapes and choose Script Based Exporter (Python) 3. In the Misc. Options tab, browse to the export script exportinstances.py and run the exporter by clicking Finish. The Python console output should read something of the form: {'zpos': [ ], 'yrot': [ ], 'asset':... {'zpos': [ ], 'yrot': [ ], 'asset': Note: The Python output console can be opened via Menu Window > Show Console. Select output consoles with the console switch dropdown on the toolbar. Adding Globals Instead of printing the data to the console, we now add a new function processinstance() that will process and collect the report values. Additionally we add two global variables (outside the finish model function) that collect the data and keep track of the instance count: # Globals ginstancedata = "" # global string that collects all data to be written ginstancecount = 0 # global count to enumerate all instances Copyright Esri. All rights reserved. 7

8 The finishmodel() Function The completed function finishmodel(): # Called for each initial shape after generation. def finishmodel(exportcontextoid, initialshapeoid, modeloid): global ginstancedata, ginstancecount model = Model(modelOID) if(model.getreports().has_key('asset')): # only write t3d entry if report data available # there might be more than one asset per model, therefore loop l = len(model.getreports()['asset']) for i in range(0,l): instancedata = processinstance(model.getreports(),ginstancecount, i-1) ginstancedata = ginstancedata+instancedata ginstancecount = ginstancecount+1 The processinstance() Function This function simply returns all the report variables in a tab-separated string: ''' Collect the instance information in a tab-separated string''' def processinstance(reports, count, index): ## remove path from asset string asset = reports['asset'][index] asset = asset.rpartition("/")[2] ## prepare the string for the instance map text = "%d\t" % count; text += "%s\t" % asset; text += "%.3f\t%.3f\t%.3f\t" % (reports['xpos'][index],reports['ypos'][index], reports['zpos'][index]) text += "%.3f\t%.3f\t%.3f\t" % (reports['xrot'][index],reports['yrot'][index], reports['zrot'][index]) text += "%.3f\t%.3f\t%.3f\n" % (reports['xscale'][index], reports['yscale'][index], reports['zscale'][index]) return text The finishexport() Function This function is called after the generation of all shapes is finished. We define the filename of the text file containing the instance map here, and call the writefile() function: # Called after all initial shapes are generated. def finishexport(exportcontextoid): global ginstancedata, ginstancecount ## path of the output file file = ce.tofspath("models")+"/instancemap.txt" ## write collected data to file writefile(file, ginstancedata) print str(ginstancecount)+"instances written to "+file +"\n" The writefile() Function... adds the header information and writes the collected report string to disk: ''' combining data (header and content) and writing file ''' def writefile(file, content): ## prepare the head string head = "nr\tasset\txpos\typos\tzpos\txrot\tyrot\tzrot\txscale\tyscale\tzscale\n" ## combine header and content content = head + content ## write data to the file report = open(file, "w") report.write(content) report.close() Running the Final Script 1. Select a set of buildings or lot shapes. 2. Start the script based exporter: File > Export... > CityEngine > Export Models of selected Shapes and choose Script Based Exporter (Python). 3. In the Misc. Options tab, browse to the export script exportinstances.py and run the exporter by clicking Finish. The resulting file instancemap.txt is saved in the model directory of the current project. nr asset xpos xrot xscale 0 scifi_building_9.obj scifi_building_17.obj scifi_building_5.obj Copyright Esri. All rights reserved. 8

Instead of writing a tab-separated text file, you can process the reported data in arbitrary ways: E.g. writing a Mel script for Maya that creates the instances, writing position information to a database or writing your custom ascii-based format.

cga to all shapes in the scene. Generate some street shapes This rule file includes futuristic arc elements on the streets. Open the CGA rule file instance_city_02.cga. Using the Report Rule In order to export the bridge instances to the instancemap as well, simply add the InstanceReport rule to the Bridge rule.

9 Instead of writing a tab-separated text file, you can process the reported data in arbitrary ways: E.g. writing a Mel script for Maya that creates the instances, writing position information to a database or writing your custom ascii-based format. Part 3: Additional Elements Thanks to the generic reporting rule, we can now easily extend our CGA rule set with additional instance elements for reporting and export. Assign instance_city_02.cga to all shapes in the scene. Generate some street shapes This rule file includes futuristic arc elements on the streets. Open the CGA rule file instance_city_02.cga. Using the Report Rule In order to export the bridge instances to the instancemap as well, simply add the InstanceReport rule to the Bridge rule. Bridge --> s(1,8,scope.sz+3.2) center(xz) i(bridge_asset) s(calcheight2(scope.sx),calcheight2(scope.sy),'1) Bridge. instancereporting.instancereport(bridge_asset) nr asset xpos... 0 bridge3.obj bridge3.obj Copyright Esri. All rights reserved. 9

Tutorial 17: Desert City Tutorial

Tutorial 17: Desert City Tutorial Table of Contents Tutorial 17: Desert city........................................... 3 2 Tutorial 17: Desert city Download items Tutorial data Tutorial PDF Prerequisites