Skip to main content

HMI Report

Introduction

The HMI Report parses your current solution and gathers information regarding the various elements that populate it. The information provided by this report can allow you to answer several questions regarding your solution. These can include, but are not limited to:

  • How many bitmaps are loaded in my solution?
  • How many of these bitmaps are actually being used within my solution?
  • What is the biggest/smallest bitmap within my solution?
  • What controls/widgets/behaviors/texts are contained in my solution, and where are they used?

The HMI report will be presented in the browser as a set of HTML documents. The documents that comprise this report are interlinked and can be navigated by using the navigation bar.


Requirements

To run the HMI reports, certain additional software is necessary, aside from SceneComposer.

  • Python 2.7.X or >= Python 3.3
    • Necessary Modules:
      • pandas
      • jinja2
      • matplotlib
      • numpy
      • pybase64
      • glob
      • shutil
      • subprocess
      • logging
      • pip (included by default with the Python binary installers starting with Python 3.4.)

Please ensure that you have Python 2.7.X or Python 3.3 or greater in your system's PATH variable, if not already set.

The exact Python version that was used for testing can be found in the Product Release Notes. Also, to check for the exact Python version installed, just run "python" in the command line as seen below:

drawing-4-1676295340.png

Any Python dependencies can be resolved by running the provisioning script in bin/Reporting/setup.bat after Python, together with pip, has been installed.

	setup.bat



Generating the Report

Upon opening Scene Composer and loading your solution, click Reports within the main toolbar. Select the Create solution report option to display the HMI Report Customization dialog box, in which you can customize several aspects of your report.

drawing-4-1676295316.png

Report Output Path is where you will designate the output location of the HMTL documents. The Styling file will specify where to retrieve the necessary .css file to apply to the documents.

The checkbox grid will allow you to customize which sub-reports are included in your report (see also next section "Report Content").

drawing-4-1676295303.png


Report Content

  • Bitmaps(summary) -> bmaps
    • An overview of all the bitmaps within your solution. Contains data on bitmap averages, largest and smallest bitmaps, referenced pixel formats, and the frequency at which said formats are referenced.
  • Bitmaps Details(detailed) -> bmapsdetails
    • Contains a paginated display and search bar for visualizing available parameter information for all bitmaps. Entries can be sorted by column.
  • Used Bitmaps(summary) -> usedbmaps
    • An overview of the referenced bitmaps within your solution. Contains data on bitmap averages, largest and smallest bitmaps, referenced pixel formats, and the frequency at which said formats are referenced.
  • Used Bitmaps Details (detailed) -> usedbmapsdetails
    • Contains a paginated display and search bar for visualizing available parameter information for all bitmaps. Entries can be sorted by column.
  • Unused Bitmaps(summary) -> unusedbmaps
    • An overview of the unreferenced bitmaps within your solution. Contains data on bitmap averages, largest and smallest bitmaps, referenced pixel formats, and the frequency at which said formats are referenced.
  • Unused Bitmaps Details(detailed) -> unusedbmapsdetails
    • Contains a paginated display and search bar for visualizing available information for all bitmaps. Entries can be sorted by column.
  • Texts -> texts
    • Contains a table summarizing the following information:
      • Text count
      • The most used text, and how often is was used.
    • A plot illustrating how much text has been translated (if multiple cultures are involved),
      • Fully: The percentage of text fully translated for all cultures. If no additional cultures are present, this parameter will display that 100% of text has been fully translated.
      • Partially: The percentage of texts missing translations in one or multiple cultures (excluding the master culture).
      • None: The percentage of texts that do not have translations in cultures other than the master culture.
    • A plot containing information regarding the percentages of use for each font.
    • A list of all used fonts and how many times each individual font is referenced.
  • Texts Details (detailed) -> textsdetails
    • Contains a list that provides the following information for each text:
      • Text ID
      • Fonts used for the said text
      • Name of the entities that are associated with said text
      • Text value
  • Controls -> controls
    • A list with the 30 most commonly used controls (if available) and how many times each control was used in all scenes.
      • Also includes a list of all controls and how many times each control was used within all available scenes.
  • Widgets -> widgets
    • A list of the 30 most popular widgets (if available) and the frequency each widget was used in all scenes.
      • Also includes a list of all widgets, indexed by widget name and each scene in which said widget was used.
  • Behaviours -> behaviors
    • A list of all behaviors and the scenes in which they are used. Also includes the scene type, behavior name, and the name of the entity associated with the behavior.
    • A list of all behaviors indexed first by name, then by the scene in which they are used.
  • 2D Scenes -> 2dscenes
    • A list of all 2D scenes within the solution. A table will be created for each scene showing the quantity of each of the following elements:
      • Bitmaps
      • Controls
      • Render Nodes
      • Text Nodes
      • Widgets
  • 2D Scenes Details (details) -> 2dscenesdetails
    • A list of all 2D scenes in the solution. A table will be created for each scene containing the names of the following elements:
      • Bitmaps
      • Controls
      • Render Nodes
      • Text Nodes
      • Widgets
  • 3D Scenes -> 3dscenes
    • A list of all 3D scenes within the solution including the number of vertices and triangle of each 3D scene.
  • Annotations -> annotations
    • A list of all annotations in the scene, for any node whose annotations property is set.
  • Rendering -> rendering
    • A list of all effects that are used, and how often each effect was used within the solution.
    • A similar list is also provided for text caching strategies.
    • A list showing which text caching strategies are associated with each node, as well as the name of the scene in which said nodes can be found.
  • Blending -> blending
    • A list of each blending combination effect and how often they have been used.
    • A list of the blending combinations indexed by combination type, scene type (2/3D), scene name, and then by the entity name associated with the blending combination.
  • Custom -> custom
    • This option is for when a custom report will be created. To activate custom report, a few lines should be uncommented in bin/Reporting/driver.py, and a scripts/custom.py should be filled out.

After selecting the report’s output path, style file, and contents, press the Generate report button to proceed with generating your report. Scene Composer will then generate several .csv files containing the requested information. Note that Scene Composer will be temporarily unavailable while the report is being generated for thread safety reasons.

Once the necessary files have been prepared, Scene Composer will process the data using python scripts and generate the report. If successful, the report will appear in your default browser.


HMI Report Data (CSV)

The CSV files within the output folder’s data subfolder contains data points available for the report:

  • 2DScenes - The names of each 2D scene.
  • 3DScenes - The names of each 3D scene and how many vertices and triangles are contained within a particular scene.
  • Custom Properties - The contents of each custom property used, as well as the custom property's client name and type.
  • Behaviors - The names of each behavior in use, as well as the names of their respective clients and scenes.
  • Bitmaps - The names of all available bitmaps and their various parameters (width, height, etc.).
  • Controls - The names and type of each control in use, as well as the name of their respective scenes.
  • FontsInfo - The font name in use and the name of the client using said font.
  • NodeBlendingOptions - All blending combinations, the scenes in which they are used, and their respective scene type.
  • Render Nodes - All render nodes, their associated effect, the scenes in which they are used, and their respective scene type.
  • SceneBitmap - All referenced bitmaps, the scenes in which they are used, and the following parameter info:
    • Width
    • Height
    • Pixel Format
    • Buffer Length
    • Pixels Occupied
  • SceneNodeCount - The number of nodes used in each scene.
  • SceneNodeDeepCount - The scene name, scene type, and number of TextNodes and RenderNodes contained in each scene.
  • SceneTransitionRule - The names of each transition rule, the scenes in which they are used, their transition type, source item, destination type, and destination item.
  • TextCache - The names of each caching strategy used within the solution alongside their respective nodes, as well as the names of the scenes in which said nodes are used.
  • TextIdClientName - The text ids contained within the solution, as well as the names of the entities referencing said text.
  • TextsInfo - The culture, text id, and base46 encoded values of each text used within the solution.
  • Widgets - The name of each widget, as well as the names and types of their respective scenes.


File Structure

HMI Reporting binaries are located within the Reporting folder of the bin directory (bin/Reporting).

  • assets
    • images - The various icons required to generate the report.
    • js - Utility scripts and other dependencies (i.e. jquery).
    • styles - The available CSS files.
    • templates - Contains the HTML templates embedded within the data.
  • doc - Contains a developers guide for the Python pipeline.
  • scripts - Contains the Python scripts responsible for generating each subreport.
  • apy.py - Contains several helper functions for computation purposes.
  • driver.py - Contains the driver logic that generates the report.
  • setup.bat - Script that install the necessary Python modules (dependencies).


Using the Command Line for Report Generation

To generate HMI reports using the command line, a script named "driver.py" is provided in the bin/Reporting directory.

Usage: driver.py [-h] --reports REPORTS [REPORTS ...] --output_file OUTPUT_FILE --style STYLE

  • --h : is an optional argument to display help information.
drawing-4-1676295276.png

The following parameters are required for report generation:

Parameters

  • --reports : Required argument, defines types of subreports to create
  • --output_file : Required argument, defines path to output directory
  • --style: Required argument, defines path to style sheet file (for example, the path to the provided style sheet file bin/Reporting/assets/styles/default.css)

You can define which subreports are added to your report with the --reports option. The argument string is created by attaching the corresponding keywords (see table below) separated with a "#".
For example:

2dscenesdetails#widgets#2dscenes#texts#textsdetails#behaviors#bmapsdetails#bmaps#rendering#usedbmapsdetails#usedbmaps
drawing-4-1676295242.png
In summary, these are the available options:
Subreport Keyword
2D Scenes 2dscenes
2D Scenes (details) 2dscenesdetails
3DScenes 3dscenes
Annotations annotations
Behaviors behaviors
Bitmaps bmaps
Bitmaps Details bmapsdetails
Used (Referenced) Bitmaps usedbmaps
Used (Referenced) Bitmaps Details usedbmapsdetails
Unused Bitmaps unusedbmaps
Unused Bitmaps Details unusedbmapsdetails
Blending blending
Controls controls
Custom custom
Rendering rendering
Texts texts
Texts Details textsdetails
Widgets widgets


Report Customization

The report will be generated based on data gathered within Scene Composer.

Scene Composer generates a set of .csv files with a fixed format, which are interpreted by python scripts to present that data. These scripts as well as the style sheets can be modified by the user to customize the style of the presentation.

In order to customize the report, knowledge of HTML/CSS/JS, a templating language (for example, Jinja), and Python (specifically, the Pandas Data Analysis tool) will be required.

You can customize your report’s appearance by using your own CSS files. The default styling sheet (default.css) is located in the bin/Reporting/assets/styles folder, and can serve as a template for future modifications.

The report’s structure can also be changed by modifying the document’s HTML template located in the bin/Reporting/assets/templates/html folder. However, knowledge of HTML, Jinja2, and JavaScript is a prerequisite.

You will need to modify the Python scripts to customize the data within your report. While knowledge of Python is required, reference documentation can be found in the bin/Reporting/doc folder.

Back to top