readme.md

ReFlex

Software Development SDK for Elastic Displays as open source mono repo

Complete Documentation as github pages available at https://visual-engineers.org/reflex/

• .NET Core library as framework for different depth sensors, calibration, depth image filtering and reconstruction of interactions
• ASP.NET Core / Angular server application as frontend for library
• can be packaged as electron app for desktop
• Example client applications for Plain HTML, Angular, React, Vue.js, Plugins for Unity, Unreal Engine 5
• Emulator as Development Tool
• Example Applications

Table of contents

1. Build status
2. Repository structure
3. External Dependencies
4. use shared code
5. NPM commands
6. Python gRPC Processing service
7. Known issues
8. Updating .NET
9. Documentation (github pages)

Build status

ReFlex Library (.NET)
Shared Types (TypeScript)
Shared Components (Angular)
Tools/TrackingServer (Angular)
Tools/Emulator (Angular)

Repository structure

Directory	Content
apps	Applications using the ReFlex framework
design	Design / Graphic source files
docs	documentation for github pages
examples	Templates and Plugins (Angular, Vue.js, React, Unreal Engine 5, Unity. .NET)
external	Place for external libraries, if needed (see External Dependencies)
library	ReFlex .NET library
packages	Shared Typescript code between applications (see Use Shared Code)
scripts	additional automation scripts either for CI or local development
services	Micro services for extending server capabilities
test	Test projects, test artifacts, Insomnia workspace
tools	Developer Tools and Server application

⬆ back to top

NPM workspaces

The repository uses NPM workspaces for better management of dependencies

Therefore, the repository should be initialized in the root folder by running the command npm install and not in the sub directories (although there are package.json files, but these files are just handling the local dependencies)

Angular workspace

All Angular applications and the shared component library are registered in the root angular.json. Their source directories and build output directories remain inside their existing npm workspaces. Angular dependencies are maintained only in the root package.json; do not add a separate angular.json to an application directory.

The existing npm scripts work both from the repository root and from each package directory. Direct Angular CLI commands should specify the project explicitly, for example:

npm run ng -- build reflex-emulator
npm run ng -- serve TrackingServer --configuration development
npm run ng -- test basic-angular --watch=false
npm run ng -- generate component example --project=shared-components-demo

To update Angular, run npm run ng -- update @angular/cli@^<next-major> @angular/core@^<next-major> from the repository root, replacing <next-major> with the target major version. Update one major version at a time, include other packages with their own migrations as needed, and review the generated changes. Dependencies no longer need to be copied into individual packages. After an update, build shared types and components first, then the applications, and run their tests. Paths in angular.json are relative to the repository root; paths in tsconfig and ng-package.json remain relative to their respective configuration files.

ESLint flat configuration

The existing lint targets use eslint.config.js in TrackingServer, emulator, shared-components-demo, and basic-react. They work through the workspace npm scripts (npm run lint:server, npm run lint:emulator, or npm run lint -w <workspace>). TrackingServer's Angular CLI lint target also uses the ESLint builder.

TrackingServer and the demo share scripts/eslint/typescript.config.cjs. It reads rule definitions from the existing GTV TypeScript policy, registers the current parser/plugins directly, and maps removed TypeScript formatting rules to @stylistic/ts. Type-aware rules resolve tsconfig.json relative to each workspace, including when ESLint is launched from the repository root. Existing generated-file and test-file exclusions are retained. The emulator additionally checks external and inline Angular templates. AngularJS's eslint-plugin-angular is not used.

Zoneless change detection

All Angular applications explicitly provide provideZonelessChangeDetection(). Their browser/SSR bootstraps and Vitest environments do not load zone.js or zone.js/testing. The shared component library is also tested in zoneless mode; it leaves the scheduling provider to its consuming application.

Imperative subscriptions that change template state call ChangeDetectorRef.markForCheck(). AsyncPipe, template events, HostListeners, and bound input updates already notify Angular. Canvas drawing and playback operate directly on the canvas and do not trigger application-wide checks.

Project	Change-detection boundaries covered by regression tests
basic-angular	WebSocket counts/frame numbers/history, connection polling, native resize and touch positions
reflex-emulator	Touch count, backup timestamp, nested layer values, connection indicator, canvas background
gestenrecorder	Loaded files/gesture table, recorder/layer forms, Plotly updates, canvas background, native hover/fix events, document clicks
shared-components-demo	HTTP responses via AsyncPipe, timed toast dismissal, projected panel state
@reflex/angular-components	Input updates for all six controls, checkbox/panel two-way bindings, debounced slider output
TrackingServer	See its ClientApp README for the HTTP/SignalR/polling/ViewChild audit

Zoneless regression tests live in the corresponding component *.spec.ts files, with application startup checks in the app spec. Shared test contexts and data live in test-utils folders. These tests assert rendered output using fixture.whenStable() without test-side detectChanges() or markForCheck(). Native timers and Plotly's drawing are awaited separately. Owned timer/stream subscriptions are detached when the affected views are destroyed; components do not unsubscribe shared service subjects.

To check all Angular projects, build the shared types and components first, then run npm run ng -- test <project> --watch=false --coverage and npm run ng -- build <project> --configuration=production for the projects above. Install the browser first with npx playwright install chromium. Angular tests use Vitest with Playwright Chromium; no CHROME_BIN setting is needed. The shared-components demo production build also verifies SSR/prerendering. Angular dependency versions remain unchanged.

⬆ back to top

Repository initialization

• run npm run build:shared-types to build shared types library
• run npm install in root directory
• for desktop builds, follow Electron builds and startup checks; no global Electron installation is required

⬆ back to top

Development

• Adding a new workspace: npm init -w ./path/to/workspace/directory
• Adding packages to workspace: npm install -w ./path/to/workspace/directory package --save (in workspace root directory)

⬆ back to top

External Dependencies

• The following dlls need to be placed in the external directory for use with the associated depth cameras
• Intel RealSense R2/D435/L515 Intel.Realsense.dll, libpxcclr.cs.dll, libpxccpp2c.dll, realsense2.dll from Intel RealSense SDK (Files are included as nuget package)
• Microsoft Kinect Microsoft.Kinect.dll, Microsoft.Kinect.xml from Microsoft Kinect for Windows SDK 2.0
• for compatibility reasons, no sensors are included in the build process by default. To include specific sensors use the appropriate flags described in the Server documentation

⬆ back to top

use shared code

• for using reflex-shared-types in another project, just install it as workspace dependency in the current project with

    npm install ./packages/reflex-shared-types -w ./tools/ReFlex.TrackingServer/ClientApp --save

• types are available by importing @reflex/shared-types

⬆ back to top

NPM commands

Command	Description	Remarks
npm run build	runs build command in all subrepos of workspace
npm run build-complete	runs build command in all subrepos of workspace, including test-ci and lint commands
npm run build:shared-types	builds package Shared Types
npm run build:shared-components	builds Shared Angular Components(#use-shared-code)
npm run build:server:electron-win	builds ReFlex.TrackingServer as Electron app packaged for Windows
npm run build:server:electron-osx	builds ReFlex.TrackingServer as Electron app packaged for OSX (Intel x64)	needs to be run on macOS
npm run build:server:electron-osx-arm64	builds ReFlex.TrackingServer as Electron app packaged for OSX (ARM64)	needs to be run on macOS
npm run build:server:electron-linux	builds ReFlex.TrackingServer as Electron app packaged for Linux (x64)
npm run build:server:electron-linux-arm64	builds ReFlex.TrackingServer as Electron app packaged for Linux (ARM64)
npm run build:emulator	builds Emulator Angular App
npm run build:emulator:electron-win	builds Emulator as Electron app packaged for Windows (x64)
npm run build:emulator:electron-osx	builds Emulator as Electron app packaged for macOS (x64)	needs to be run on macOS
npm run build:emulator:electron-osx-arm64	builds Emulator as Electron app packaged for macOS (ARM64)	needs to be run on macOS
npm run build:emulator:electron-linux	builds Emulator as Electron app packaged for Linux (x64)
npm run build:emulator:electron-linux-arm64	builds Emulator as Electron app packaged for Linux (ARM64)
npm run build:example-angular	builds Angular Template
npm run build:example-react	builds React Template
npm run build:example-vue	builds Vue.js Template
npm run build:logging	builds Logging tool
npm run start:emulator	build and start Emulator Angular app on localhost:4300
npm run start:example-angular	build and start Angular Template on localhost:4201
npm run start:example-react	build and start React Template on localhost:3000
npm run start:example-vue	build and start Vue.js Template on localhost:8080
npm run start:logging	build and start Logging tool on localhost:4302
npm run start:server	build and start ReFlex.TrackingServer tool (only Angular frontend) on localhost:4200	Server backend must be started separately
npm run lint:emulator	executes linter on Emulator project
npm run lint:server	executes linter on ReFlex.TrackingServer project
npm run test:emulator	executes tests on Emulator project
npm run test:net-with-report	executes .NET tests on .NET Solution ReFlex.sln and generates report for tests	Currently only compatible with Windows
npm run test:server	executes tests on ReFlex.TrackingServer project
npm run update:server:dependencies.	updates tools/ReFlex.TrackingServer/ClientApp/src/assets/data/package.json with current npm dependicies and their version info

Known issues (NPM commands)

• Electron packaging uses isolated application files. See Electron builds and startup checks for prerequisites, platform targets and CI smoke tests.
• Angular test and build-complete commands require Playwright Chromium: run npx playwright install chromium after npm ci.

⬆ back to top

Python gRPC Processing service

• as an example for integrating external services, a python gRPC service for extracting interactions from the camera depth image is provided in services/python-backend
• service is consumed when setting Interaction Processor to Remote
• in the ReFlex.TrackingServer, the service is configured in Services/RemoteInteractionProcessingService.cs
• Documentation: Python gRPC service

⬆ back to top

Known issues

• if an application behaves different when executing the packaged electron version (either installed using the setup or the executable in the win-unpacked directory)), this may be caused by outdated Electron Cache. In this case, open

  • %AppData% Folder (Windows)
  • ~/.config Folder (Linux)
  • ~/Library/Application Support/ (MacOS)
    and delete the app folder there

• to delete all temporary folders / cached packages / build artifacts, run the following command in the scripts folder:

   ./cleanup_packages.sh package-directories.txt

⬆ back to top

Updating .NET

• The .NET version which is used to build the ReFlex Solution is specified in the global.json file in the root directory
• .NET versions must be updated in all projects (library) and Server component of tools/ReFlex.TrackingServer as well als examples/ExampleWPF and examples/MAUI
• After a .NET Update this need to be changed to the matching .NET version in global.json, to ensure compatibility
• global.json is needed especially for CI, as th github action setup-dotnet by defauilt installs the newest version and build the solution with this version, which is likely to cause errors

⬆ back to top

Documentation (github pages)

Documentation is hosted as github page at https://visual-engineers.org/reflex.

The documentation content for the github pages can be found in the docs folder.

repository readme files

readme files in the repository (including this file) are copied into the docs directory as part of the deployment CI step by executing the scripts\copy_docs.sh shell script.

The related readme files are:

repo readme	target directory	section in pages
readme.md	docs/software/repo/reflex.md	Software > Repository > ReFlex Framework
library/README.md	docs/software/repo/library.md	Software > Repository > ReFlex Library (.NET)
tools/ReFlex.TrackingServer/readme.md	docs/software/apps/server.md	Software > Applications > Server
tools/logging/README.md	docs/software/apps/logging.md	Software > Applications > Logging
tools/emulator/README.md	docs/software/apps/emulator.md	Software > Repository > Emulator

Testing github pages locally

testing the github pages can be done by following the instruction at Github Docs: Testing your GitHub Pages site locally with Jekyll

⬆ back to top