{"id":13680670,"url":"https://github.com/risa2000/hmdq","last_synced_at":"2025-04-30T00:30:39.292Z","repository":{"id":48127271,"uuid":"200224638","full_name":"risa2000/hmdq","owner":"risa2000","description":"HMDQ Tools - the tools for VR headsets and other hardware introspection","archived":false,"fork":false,"pushed_at":"2025-04-20T16:07:37.000Z","size":666,"stargazers_count":40,"open_issues_count":2,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-20T17:23:53.726Z","etag":null,"topics":["hardware-introspection","openvr","vr","vr-headset"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/risa2000.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-08-02T11:39:39.000Z","updated_at":"2025-04-20T16:07:41.000Z","dependencies_parsed_at":"2024-01-14T17:04:43.882Z","dependency_job_id":"d100a90a-9cd7-4ec2-a3ed-007fc0ef66b0","html_url":"https://github.com/risa2000/hmdq","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/risa2000%2Fhmdq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/risa2000%2Fhmdq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/risa2000%2Fhmdq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/risa2000%2Fhmdq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/risa2000","download_url":"https://codeload.github.com/risa2000/hmdq/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251607302,"owners_count":21616736,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hardware-introspection","openvr","vr","vr-headset"],"created_at":"2024-08-02T13:01:20.100Z","updated_at":"2025-04-30T00:30:39.284Z","avatar_url":"https://github.com/risa2000.png","language":"C++","funding_links":[],"categories":["C++"],"sub_categories":[],"readme":"![hmdq](docs/images/hmdq_128.png) ![hmdv](docs/images/hmdv_128.png)\n\n# HMDQ Tools\nHMDQ Tools is a set of two command line tools for VR headsets and other hardware introspection with support for both OpenVR and Oculus runtimes. The tools are also used to collect the data for and build the [HMD Geometry Database](https://risa2000.github.io/hmdgdb/).\n\n## `hmdq`\nis a main tool, which connects to a VR subsystem and collects all available data about the connected devices (_tracked devices_ in OpenVR world, headsets, trackers and controllers in Oculus world).  \n\nIt can either display the info in the console, or save all the collected information plus some additional calculated data to a file in JSON format.\n\nOne needs to have either OpenVR or Oculus runtime plus the corresponding hardware installed and connected to use the tool.\n\n## `hmdv`\nis a complementary tool, whose only purpose is to process the data files created by `hmdq` and display them in a human friendly way.\n\nBoth tools use very similar command line interface. The only (major) difference is that `hmdq` reads the data it shows (and stores) from actual VR runtime, while `hmdv` reads the data from already stored file. The following paragraphs address both tools, unless it is explicitly specified otherwise.\n\n## Installation\nGet the latest binary ZIP from [releases](https://github.com/risa2000/hmdq/releases) and unzip it wherever you want to run it. The package should contain both `hmdq` and `hmdv` tools, this README file, LICENSE file, OpenVR API JSON file and some additional files to ease the use.\n\n## Operation\nSince both tools are command line tools, it is better to run them from Windows console or any terminal (window) which supports standard I/O.\n\nWhen the tools run the first time, they create a configuration file `\u003ctool_name\u003e.conf.json` in the same directory.\n\nAnother file which is necessary (and is present in the archive) is OpenVR API description file (`openvr_api.json`). This file can be updated independently of HMDQ tools.\n\n### Commands\n\n#### `help`\nShows all the commands and options with short descriptions.\n\n* `hmdq`\n```\n$ hmdq help\nUsage:\n        hmdq (geom|props|all) [-a \u003cname\u003e] [-o \u003cname\u003e] [-v [\u003clevel\u003e]] [-n] [--openvr] [--oculus]\n             [--ovr_max_fov]\n\n        hmdq version\n        hmdq help\nOptions:\n        geom        show only geometry data\n        props       show only device properties\n        all         show all data (default choice)\n        -a, --api_json \u003cname\u003e\n                    OpenVR API JSON definition file\n                    [\"D:\\Work\\vsprojects\\hmdq\\out\\build\\x64-DLL-Debug\\hmdq\\openvr_api.json\"]\n\n        -o, --out_json \u003cname\u003e\n                    JSON output file\n\n        -v, --verb \u003clevel\u003e\n                    verbosity level [0]\n\n        -n, --anonymize\n                    anonymize serial numbers in the output [false]\n\n        --openvr    show only OpenVR data\n        --oculus    show only Oculus data\n        --ovr_max_fov\n                    show also Oculus max FOV data\n\n        version     show version and other info\n        help        show this help page\n```\n* `hmdv`\n```\n$ hmdv help\nUsage:\n        hmdv (geom|props|all) [-a \u003cname\u003e] [-o \u003cname\u003e] [-v [\u003clevel\u003e]] [-n] [--openvr] [--oculus]\n             [--ovr_max_fov] \u003cin_json\u003e\n\n        hmdv verify \u003cin_json\u003e\n        hmdv version\n        hmdv help\nOptions:\n        geom        show only geometry data\n        props       show only device properties\n        all         show all data (default choice)\n        -a, --api_json \u003cname\u003e\n                    OpenVR API JSON definition file\n                    [\"D:\\Work\\vsprojects\\hmdq\\out\\build\\x64-DLL-Debug\\hmdv\\openvr_api.json\"]\n\n        -o, --out_json \u003cname\u003e\n                    JSON output file\n\n        -v, --verb \u003clevel\u003e\n                    verbosity level [0]\n\n        -n, --anonymize\n                    anonymize serial numbers in the output [false]\n\n        --openvr    show only OpenVR data\n        --oculus    show only Oculus data\n        --ovr_max_fov\n                    show also Oculus max FOV data\n\n        \u003cin_json\u003e   input data file\n        verify      verify the data file integrity\n        \u003cin_json\u003e   input data file\n        version     show version and other info\n        help        show this help page\n```\n\n#### `geom`\nDisplays the headset geometry which is normally advertised by VR subsystem to the application. It includes:\n\n* View geometry (rendered FOVs) for each eye.\n* Total stereo rendered FOVs and the overlap.\n* Rotation of the virtual cameras (views).\n* IPD value.\n\nAdditionally to that, it also shows:\n\n* The recommended render target resolution.\n* The size of the _hidden area mask_ (HAM) mesh (if supported by the headset).\n\nExample (excerpt):\n```c\nTotal FOV:\n    horizontal: 108.77 deg\n    vertical:   111.48 deg\n    diagonal:   113.18 deg\n    overlap:     93.45 deg\n\nView geometry:\n    left view rotation:     0.0 deg\n    right view rotation:    0.0 deg\n    reported IPD:           63.0 mm\n```\n\n#### `props`\nPrints out all different _properties_ for all currently detected _devices_. For OpenVR it includes not only the headset and the controllers, but also the lighthouses and the additional (not lighthouse tracked) devices as the gamepads. The number of properties shown depends on the _verbosity_ level specified by the user, which, by default, is set to `0`.\n\nExample (excerpt):\n```c\nDevice enumeration:\n    Found dev: id=0, class=1, name=HMD\n    Found dev: id=1, class=4, name=TrackingReference\n    Found dev: id=2, class=4, name=TrackingReference\n\n[0:HMD]\n    1000 : TrackingSystemName = \"lighthouse\"\n    1001 : ModelNumber = \"Vive. MV\"\n    1002 : SerialNumber = \"anon@1B02287EBB399418DC264E14\"\n    1003 : RenderModelName = \"generic_hmd\"\n    1004 : WillDriftInYaw = false\n    1005 : ManufacturerName = \"HTC\"\n    1006 : TrackingFirmwareVersion = \"1462663157 steamservices@firmware-win32 2016-05-08 FPGA 262(1.6/0/0) BL 0\"\n    1007 : HardwareRevision = \"product 128 rev 2.1.0 lot 2000/0/0 0\"\n    1008 : AllWirelessDongleDescriptions = \"anon@E0274499D83512E548FB4966\"\n    2001 : SecondsFromVsyncToPhotons = 0.0111111\n    2002 : DisplayFrequency = 90\n```\n\n#### `version`\nShows the tool version info plus some additional information about the build and the used libraries.\n\n#### `verify` (only in `hmdv`)\nVerifies the data file checksum.\n\n#### `all (default)`\nProcesses both `geom` and `props`. This is the default command.\n\n### Options\n\n#### `--api_json \u003cfilename\u003e`\nAllows specifying a custom/different/new JSON file with OpenVR API definitions. Normally, you should not need that. The one included comes directly from [OpenVR repository](https://github.com/ValveSoftware/openvr/tree/master/headers).\n\nYou can update this file independently from the tools to let them recognize new properties (if there were any).\n\n#### `--out_json \u003cfilename\u003e`\nWhen specified, all the information collected by the tool (not only what is actually displayed in the console, but all possible retrievable information), plus some additional information calculated by the tool in the process (e.g. different _FOV points_, HAM mesh optimized layout, etc.) is stored in the specified file in JSON format.\n\nThis file is mostly useful for additional processing, evaluation, and future reference.\n\n**NOTE:** _The amount of the information stored in the file, **is not controlled by the verbosity level**. Every time the file is created, all the available information plus the additionally computed data are stored in the file. The reason for that is to have a well defined set of data, which is guaranteed to be present._\n\nWhen this option is used with `hmdv` it just rewrites the information from the input file to the output file. It is useful to anonymize the input file or to update the data content to the latest version (see the Changelog file for the details).\n\n#### `-v \u003clevel\u003e, --verb \u003clevel\u003e`\nVerbosity level of the output (to the console). There are five levels defined:\n\n* `--verb -1`  \nSilent running. Shows only the basic startup info.\n* `--verb 0 (default)`  \nThe default one, shows just the basic information in both `geom` and `props` modes.\n* `--verb 1`  \nAll the information available for `geom` part is displayed, and the basic information for `props`.\n* `--verb 2`  \nAdds few more properties in `props` mode (specified in the config file).\n* `--verb 3`  \nShows all the properties, which are supported by each device currently detected and identified by the system.\n* `--verb 4`  \nAdds as well all the properties, which are defined by the OpenVR API, but are neither supported by the devices, nor are supported by the tool itself (the reason is explained by the error message given in the console output).\n\nThe levels can be redefined in the configuration file. The values listed above are the default ones.\n\n#### `-n, --anonymize`\nIf specified, it will anonymize values of some \"sensitive\" properties defined in the configuration file. Others can be added to the config file if needed.\n\nThe anonymization happens in both the console output and in the output JSON file.\n\nThis could be useful when sharing the output data publicly, without disclosing the unique identifiers.\n\nThe anonymized values are computed by using the secure hash function [Blake2](https://blake2.net) set with 96-bit wide output. The hash is computed over three properties: manufacturer name (#1005 `Prop_ManufacturerName_String` in OpenVR), concatenated with model name (#1001 `Prop_ModelNumber_String` in OpenVR), and finally with the incriminated value to anonymize. The manufacturer and model names are used to pre-seed the hash with distinct values, so the same serial numbers from different manufacturers will not anonymize into the same values.\n\n#### `--openvr`\nWill only show data collected from OpenVR runtime (if one is present and any hardware is connected).\n\n#### `--oculus`\nWill only show data collected from Oculus runtime (if one is present and a headset is connected).\n\nBoth options are meant to only control the program output, but the data are logged and saved into the data file (if requested by `--out_json` option) for both subsystems.\n\n#### `--ovr_max_fov`\nShows also data for Oculus headset _Maximum FOV_.\n\n### Configuration\nThe configuration file `\u003ctool_name\u003e.conf.json` is always created with the default values, and can be changed later by the user. The tool will not \"touch\" the configuration file as long as it exists and only create a new one if none is present.\n\nIt has a consequence when updating the tool to the newer version. It may happen that the new version of the tool introduces new config values, which are not present in the old configuration file, or remove some old ones. When it happens the tool will refuse to run and ask the user to manually update the configuration file.\n\nOne way how to do it is letting the tool to create a new (default) config file (e.g. by renaming the old one) and then manually copy any custom setting from the old config to the new one.\n\nConfiguration options:\n\n* `meta` section is read-only. Changing it has no meaning or impact on the tool operation.\n* `control`\n    * `anonymize` decides whether the sensitive data (the serial numbers) are anonymized by default. Default value is `false`.\n* `format` defines the indentation (in spaces):\n    * `cli_indent` for standard output in the console,\n    * `json_indent` for the output JSON file.\n* `verbosity` defines all the different verbosity levels to which the user specified verbosity (set by `--verb` on the command line) is compared.\n    * `silent` defines the level, which, when specified by user, will display only the basic startup info.\n    * `default` is default verbosity level which the tool will use, when none is specified on the command line.\n    * `geom` is the level at which all the geometry properties (displayed in `geom` command) are shown.\n    * `max` defines the level at which all properties _with meaningful values_ are included in the console output.\n    * `error` - the level which, when specified, will also display unsupported properties (with errors).\n* `openvr` (only used by OpenVR runtime or when processing OpenVR data)\n    * `app_type` defines how the tool initializes the OpenVR subsystem in `vr::VR_Init` call. The different application types are described [here](https://github.com/ValveSoftware/openvr/wiki/API-Documentation#initialization-and-cleanup).  \n    **Note**: _Basically anything different from the default value is untested and unsupported. Putting in a wrong type can also impact the reported values. So only change it if you know what you are doing._\n    * `verbosity`\n        * `properties` defines individual verbosity levels for listed properties. The default list is more of an example than some sophisticated choice. The number defines the minimal required verbosity level specified by the user, in order to have the property value displayed in the output.\n    * `anonymize`\n        * `properties` defines a list of tracked device properties which are anonymized, if requested either by the user with the command line option or by specifying the default behavior in the config file.\n* `oculus` (only used by Oculus runtime or when processing Oculus data)\n    * `init_flags` default value for the runtime initialization.\n    * `verbosity` (the same as for OpenVR)\n    * `anonymize` (the same as for OpenVR)\n\n## Theory behind the FOV calculations\nWhile listing the properties of (tracked) devices is a mundane task, the rendered FOV calculation is an interesting topic which deserves its own space and is in detail dissected here [VR headset rendered FOV calculation](https://risa2000.github.io/vrdocs/docs/hmd_fov_calculation).\n\n## Building the tool from the source code\nThe tools are being developed as a fun project, so they are probably overdone on many levels, but should never the less be buildable.\n\n### Required external libraries\n* [`muellan/clipp`](https://github.com/muellan/clipp)\nfor parsing the command line arguments.\n* [`QuantStack/xtensor`](https://github.com/QuantStack/xtensor) for all 2D, 3D vectors and matrices operations.\n* [`QuantStack/xtl`](https://github.com/QuantStack/xtl) required by `QuantStack/xtensor`.\n* [`nlohmann/json`](https://github.com/nlohmann/json) for all JSON parsing and creating.\n* [`ValveSoftware/openvr`](https://github.com/ValveSoftware/openvr) for obvious reasons.\n* [`randombit/botan`](https://github.com/randombit/botan) for secure hash implementation.\n* [`fmtlib/fmt`](https://github.com/fmtlib/fmt) for comfortable printing and formatting of the console output.\n* [`Oculus SDK`](https://developer.oculus.com/downloads/package/oculus-sdk-for-windows/)\n* [`libeigen/eigen`](https://gitlab.com/libeigen/eigen) for FOV calculations.\n* [`libgeos/geos`](https://github.com/libgeos/geos) for HAM area calculation.\n\nOn top of that you will also need `cmake` version 3.15 or higher.\n\n### Optional external libraries\n* [`Catch2`](https://github.com/catchorg/Catch2) to build unit tests.\n\n### Building\n\n#### Building with CMake\nThe project is developed as a CMake project in Visual Studio 2022, while using `ninja` as a build driver. The binaries can be successfully built by native MSVC compiler `cl` or by LLVM `clang-cl` (Clang drop in replacement for MSVC compiler).\n\nTo have the automatic versioning working correctly, CMake scripts expect the build to happen in a locally cloned `git` repository.\n\n#### Building with Conan\nThis is a preferred and also the easiest way. The local `conan/packages` folder contains the conan recipes and build scripts for packages which are not in conan-center (or have older/incompatible versions there). In order to be able to initialize the conan build environment you need to run the batch files in the corresponding subfolders first to build and install the missing packages into the local conan cache.\n\nThen you need to run `conan/conan_install_all.cmd` batch to build and install the remaining packages. The conan files are installed into specific directories, where the Visual Studio CMake integration (using `CMakeSettings.json`) expects them. After that you can use VS IDE to build the binaries as you would for any other CMake project.\n\nThe only dependency which does not have a public or local conan package or recipe is `LibOVR` as it needs to be downloaded from the Oculus website and set up manually, by setting `OVR_SDK` environment variable to the library root folder (e.g. `OVR_SDK=C:\\ovr_sdk_win_32.0.0`).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frisa2000%2Fhmdq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frisa2000%2Fhmdq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frisa2000%2Fhmdq/lists"}