Spatial Interaction Logging & Session Architecture

Overview

A responsive environment can react successfully to visitors without recording anything about what occurred.

For an interactive installation, this may be sufficient.

For a research environment, however, the system must preserve selected aspects of the interaction in a form that can later be reconstructed, inspected, and analyzed.

This creates a second responsibility alongside real-time interaction:

the experience must respond now, while the research system must preserve what happened for later analysis.

Research logging should be treated as part of the system architecture rather than as a recording feature added after the experience has already been built.

A useful logging architecture connects spatial observations, interaction events, experience states, and system events through a common session identity.

The architecture should also distinguish between three different concepts:

1. Primary observations — what the system directly records.
2. Derived metrics — measurements calculated from those observations.
3. Study-specific instruments — additional data required by a particular research study.

This separation makes the logging infrastructure reusable across different responsive environments without forcing every deployment to collect exactly the same information.

---

1. From Interactive System to Research Instrument

A conventional responsive system may follow:

System Architecture

Left → Right

The system observes the visitor and responds.

A research-oriented system adds another path:

System Architecture

Left → Right

The same spatial infrastructure now serves two purposes.

The experience path supports immediate response.

The research path preserves structured observations.

Neither path should unnecessarily depend on the internal implementation of the other.

---

2. What Should Be Logged?

Recording everything is rarely necessary.

A research logging system should begin with the questions that later analysis needs to answer.

Possible observations include:

Session information

session_id
session_start
session_end
session_status

Spatial information

x
y
visitor_id
area
tracking_state

Interaction information

area_enter
area_exit
interaction_start
interaction_complete

Experience information

scene_enter
scene_exit
content_trigger
experience_complete

System information

sensor_connected
sensor_disconnected
tracking_lost
runtime_error

These observations have different purposes and should not automatically be stored in one undifferentiated log.

---

3. Primary Observations and Derived Measures

A fundamental distinction should be made between what the system observes and what researchers later calculate.

For example, the system may record:

area_enter = 12.40 s
area_exit  = 21.85 s

From these observations, analysis can derive:

dwell_time = 9.45 s

Similarly, the logger may preserve:

x
y
timestamp

while analysis later produces:

trajectory length
movement speed
spatial density
heatmap

The logging architecture should therefore preserve sufficiently detailed primary observations without prematurely converting every observation into an analytical conclusion.

System Architecture

Left → Right

---

4. The Session as the Primary Unit

A research dataset needs a unit that groups observations belonging to the same experience.

For many responsive environments, this unit can be a session.

For example:

S0001
S0002
S0003

A session begins according to an explicit rule.

Possible rules include:

visitor detected
check-in completed
experience started
room state changed to active

It ends according to another explicit rule:

experience completed
visitor left
room returned to idle
timeout occurred

The exact definition depends on the study.

What matters is that the definition remains consistent during data collection.

---

5. Shared Session Identity

Distributed installations may produce data on several machines.

For example:

Sensor Server
→ spatial tracking

TouchDesigner
→ interaction and scene events

Room Controller
→ experience state

Study Interface
→ questionnaire or additional research data

Without a common identifier, these records become difficult to associate later.

A shared session ID provides the connection.

System Architecture

Left → Right

Each subsystem records the same identifier:

session_id = S0042

Separate datasets can then be associated during analysis.

---

6. Session ID Design

A session identifier should primarily be:

• unique within the dataset
• easy for machines to exchange
• independent of personally identifying information
• stable for the duration of the session

A simple format may be:

S000001

A deployment-aware format might be:

FL-20261212-0001

where:

FL
→ deployment identifier

20261212
→ collection date

0001
→ session sequence

The identifier itself does not need to contain the visitor's name.

Research identity and personal identity should remain separate unless a study explicitly requires and appropriately governs their connection.

---

7. Session Lifecycle

A session can be represented as a state model.

This makes termination explicit.

An interrupted experience should not simply disappear from the dataset.

It may instead be recorded as:

status = aborted

Other possible statuses may include:

completed
aborted
timeout
system_error
partial

This preserves the difference between complete and incomplete sessions.

---

8. Time as a Shared Reference

Spatial research depends heavily on time.

A position without a timestamp cannot form a trajectory.

An interaction event without time cannot reliably be aligned with movement or scene changes.

Every observation should therefore include a temporal reference.

For example:

session_id,timestamp,x,y
S0042,0.000,1.42,2.18
S0042,0.100,1.45,2.20
S0042,0.200,1.51,2.23

The timestamp may represent elapsed time from session start:

0.000
0.100
0.200

or an absolute timestamp where required.

Session-relative time is particularly useful for reconstructing the temporal progression of individual experiences.

---

9. Distributed Time

A distributed system introduces an additional problem.

Several machines may have different local clocks.

For example:

Sensor Server timestamp
TouchDesigner timestamp
Room Controller timestamp

If these clocks differ, an interaction may appear to occur before or after the movement that caused it.

A robust architecture therefore needs a timing strategy.

Possible approaches include:

• synchronized machine clocks
• one central timestamp authority
• session-relative timestamps
• recording both local and shared timestamps

The appropriate solution depends on the temporal precision required by the study.

The important methodological requirement is to know what each timestamp represents.

---

10. Continuous Spatial Logging

Spatial tracking produces continuous observations.

A minimal trajectory record may contain:

session_id
timestamp
x
y

For example:

S0042,0.000,1.42,2.18
S0042,0.100,1.45,2.20
S0042,0.200,1.51,2.23

Additional fields may include:

visitor_id
area
tracking_state
source

A more complete record might therefore be:

session_id,timestamp,visitor_id,x,y,area
S0042,0.000,V01,1.42,2.18,area_1

The schema should contain fields required by the intended analysis rather than every value available from the sensor.

---

11. Sampling Rate

Continuous logging does not necessarily mean storing every sensor update.

A sensor may produce observations faster than the research question requires.

For example:

sensor
→ high-frequency measurement

research logger
→ selected sampling rate

The appropriate sampling rate depends on:

• visitor movement speed
• room scale
• interaction precision
• desired trajectory detail
• storage requirements
• processing capacity

Reducing the sampling rate can decrease unnecessary data while preserving meaningful movement patterns.

However, the sampling decision should be documented because it affects the resolution of later analysis.

---

12. Event Logging

Not every observation should be stored continuously.

Discrete changes are better represented as events.

Examples include:

session_start
visitor_enter
area_enter
interaction_start
interaction_complete
scene_enter
experience_complete
visitor_exit
session_end

An event log may contain:

session_id,timestamp,event_type,target
S0042,0.000,session_start,
S0042,3.240,area_enter,area_1
S0042,8.510,interaction_start,interaction_1
S0042,15.220,area_exit,area_1
S0042,62.410,experience_complete,
S0042,66.100,session_end,

Events provide meaningful boundaries within continuous behaviour.

---

13. Continuous Data and Event Data

A useful research system often records both.

System Architecture

Left → Right

Continuous data answers:

Where was the visitor over time?

Event data answers:

What meaningful interaction occurred and when?

Together they provide substantially more context than either representation alone.

---

14. Experience-State Logging

Scene transitions from the experience architecture can also become research observations.

For example:

intro_start
active_start
interaction_scene
completion_start
reset

A scene log can help determine whether movement occurred during:

• introduction
• active interaction
• transition
• completion

Without scene context, a trajectory may show where the visitor moved but not what the environment was presenting at that moment.

---

15. A Unified Event Vocabulary

Distributed applications should avoid inventing inconsistent names for the same event.

For example:

area1_on
zone1_enter
triggerA
interaction_1

may accidentally describe related or identical conditions.

A shared vocabulary is easier to analyze.

Recommended core events include:

session_start
session_end

visitor_enter
visitor_exit

area_enter
area_exit

interaction_start
interaction_complete

scene_enter
scene_exit

experience_complete

Additional information can be represented separately.

For example:

event_type = area_enter
target = area_1

rather than defining a completely different event type for every interaction area.

---

16. Dwell Time

Dwell time should normally be derived from clearly defined event boundaries.

For an area:

area_enter
      ↓
time inside area
      ↓
area_exit

Then:

dwell_time =
exit_timestamp - enter_timestamp

For example:

area_enter = 12.40
area_exit  = 21.85

dwell = 9.45 seconds

The measurement becomes reproducible because it is derived from explicit observations.

---

17. Dwell Is Not One Metric

Several forms of dwell may be relevant.

Spatial Dwell

Time spent inside a physical region.

Interaction Dwell

Time actively engaged with an interactive element.

Scene Dwell

Time spent within a particular experience state.

Session Duration

Total time from session start to session end.

These measurements should remain conceptually distinct even if they are calculated from the same underlying timestamps.

---

18. Interaction Count

Interaction count also requires an operational definition.

Consider a visitor who remains inside an interaction zone for ten seconds.

Counting every tracking frame would produce hundreds of interactions.

Instead, an interaction may be defined as:

outside
↓
enter area
↓
minimum dwell reached
↓
interaction confirmed

Only the confirmation event is counted.

Another study may define:

area_enter = one interaction

Both definitions are possible.

The important requirement is that the rule is explicit and applied consistently.

---

19. Repeated Interaction

A visitor may return to the same interaction several times.

For example:

Area 2 enter
Area 2 exit
Area 2 enter
Area 2 exit

This can later produce:

area_visit_count(area_2) = 2

Repeated interaction may potentially relate to exploration, preference, uncertainty, or intentional revisiting.

The logger itself should not assume which interpretation is correct.

Its responsibility is to preserve the behaviour accurately enough for later analysis.

---

20. Trajectory Reconstruction

Continuous position records can reconstruct a movement trajectory.

A trajectory is a sequence:

(x1, y1, t1)
(x2, y2, t2)
(x3, y3, t3)
...

Conceptually:

System Architecture

Left → Right

A trajectory can later support calculations such as:

• path visualization
• movement distance
• approximate movement speed
• area transitions
• spatial exploration
• temporal progression

A shared room coordinate system, as described in K03, is important for meaningful reconstruction.

---

21. Heatmaps

Spatial samples can be aggregated into a heatmap.

Conceptually:

position samples
      ↓
spatial grid
      ↓
frequency or duration
      ↓
heatmap

Two heatmaps may represent different measures.

Frequency Heatmap

How frequently observations occurred within each spatial region.

Dwell Heatmap

How much accumulated time occurred within each region.

These should not automatically be interpreted as equivalent measures.

---

22. Heatmaps Need Context

A high-density region may occur because:

• an interaction attracted visitors
• the content required waiting
• room geometry constrained movement
• visitors paused before making a decision
• the entrance or exit was located there

The heatmap alone cannot determine why the behaviour occurred.

Combining spatial data with:

scene state
interaction events
dwell
questionnaire responses
qualitative observations

can provide additional context.

Research logging should therefore support multiple forms of evidence rather than treating spatial data as self-explanatory.

---

23. Logging Multiple Sensors

A multi-sensor system may generate several observations of the same visitor.

Research logging should distinguish between:

sensor-level observations

and

research-level spatial estimates.

For example, diagnostic data may contain observations from:

lidar_left
lidar_right
floor_lidar_1
floor_lidar_2

while the research trajectory contains:

visitor_id
x
y
timestamp

Conceptually:

System Architecture

Left → Right

This prevents the same visitor from automatically becoming several research observations simply because multiple sensors detected them.

---

24. Canonical CSWORKS Logging Schema

The logging architecture benefits from a small, stable core schema that can be reused across different responsive-environment deployments.

The purpose of the core schema is not to describe every possible study variable.

It defines the minimum structural relationship between:

session
time
space
interaction
experience
system

Study-specific variables can extend this foundation when required.

---

24.1 Core Session Schema

The session table defines the identity and lifecycle of each recorded experience.

The session_id acts as the primary link between the different data streams generated during an experience.

duration_s may be stored as a convenience after finalization, but it remains derivable from the session boundaries.

---

24.2 Trajectory Schema

Continuous spatial observations are stored separately from lower-frequency events.

A trajectory can be reconstructed by grouping records by session_id and visitor_id, then ordering them by timestamp.

The shared coordinate system should remain consistent for the duration of a deployment.

---

24.3 Interaction Event Schema

Discrete changes are recorded as events rather than repeated every tracking frame.

Recommended core event vocabulary includes:

session_start
session_end

visitor_enter
visitor_exit

area_enter
area_exit

interaction_start
interaction_complete

scene_enter
scene_exit

experience_complete

The vocabulary can be extended by a study, but core events should retain consistent meanings across deployments.

---

24.4 System Event Schema

Technical events should remain distinguishable from behavioural observations.

Possible events include:

sensor_connected
sensor_disconnected
tracking_lost
tracking_restored
runtime_started
runtime_stopped
network_error
logging_error

System logs provide context for evaluating whether unusual behavioural records may have occurred during a technical problem.

---

24.5 Example Core Dataset

A simple deployment can therefore maintain:

session_S0042/
│
├── session.csv
├── trajectory.csv
├── events.csv
└── system.csv

session.csv

session_id,deployment_id,start_time,end_time,status,participant_count,system_version

trajectory.csv

session_id,timestamp,visitor_id,x,y,area,tracking_state,source

events.csv

session_id,timestamp,source,event_type,target,value,visitor_id

system.csv

session_id,timestamp,component,event_type,value,severity

These files represent the core research logging infrastructure.

Study instruments are intentionally not included in this core directory definition.

---

24.6 Derived Metrics

Not every research variable needs to be stored directly.

Several measures can be calculated from the primary records.

This distinction is important.

The logger preserves observations.

The analysis layer derives metrics.

The research interpretation then examines what those metrics may mean in relation to the study question.

System Architecture

Left → Right

---

24.7 Core Schema vs Study-Specific Fields

The core schema should remain relatively stable across CSWORKS research deployments.

CORE

session_id
timestamp
visitor_id
x
y
area
event_type
target
source

Individual studies can extend this schema.

For example:

theme_id
content_id
interaction_id
condition_id
sensor_configuration
room_configuration

These fields belong to a study-specific implementation when they are not meaningful across other deployments.

The relationship is:

System Architecture

Left → Right

This allows different responsive environments to share a common analytical foundation without forcing every installation to collect identical information.

---

25. Study-Specific Instruments

Questionnaires, interviews, observation sheets, and experimental conditions should be treated as study instruments rather than as core spatial logs.

For example:

STUDY INSTRUMENTS

questionnaire responses
interview responses
researcher observations
experimental condition
content condition
participant metadata

These records can still connect to the spatial dataset through:

session_id

Conceptually:

System Architecture

Left → Right

The shared identifier enables later integration without requiring the sensor infrastructure to understand the structure of every research instrument.

---

26. Example Study Extension

A specific study might require additional information.

For example:

session_id
theme_id
content_id
condition_id
questionnaire_version

A study-specific table could contain:

session_id,theme_id,content_id,condition_id
S0042,theme_03,content_02,condition_A

The core trajectory data remains unchanged:

session_id,timestamp,visitor_id,x,y,area

This separation allows the same logging system to support multiple studies.

---

27. Source Attribution

Every event should identify where it originated when several systems can generate logs.

Possible sources include:

sensor_server
touchdesigner
unity
room_controller
study_interface

For example:

source = sensor_server
event_type = area_enter

or:

source = touchdesigner
event_type = interaction_start

Source attribution helps distinguish:

what the sensing system detected

from

what the experience actually executed.

This distinction can become important when diagnosing delayed or failed responses.

---

28. Logging the Cause and the Response

Consider:

visitor enters Area 1

The sensing system records:

area_enter

The experience then records:

interaction_start

Keeping both events allows later verification that:

detected interaction
→ produced expected response

The sequence may look like:

This creates a more complete record of the interaction pipeline.

---

29. Missing and Interrupted Sessions

Real installations produce imperfect data.

Possible conditions include:

visitor leaves early
sensor temporarily loses tracking
application restarts
network disconnects
study instrument not completed

The logging architecture should preserve these conditions rather than silently treating every session as complete.

Possible session status values may include:

completed
aborted
timeout
system_error
partial

This makes later filtering transparent.

---

30. System Health Logging

Research data can become difficult to interpret if the system was malfunctioning during collection.

A lightweight system log can therefore record:

sensor_connected
sensor_disconnected
runtime_started
runtime_stopped
network_error
tracking_lost
tracking_restored
logging_error

These events remain separate from the primary behavioural dataset.

Their role is to provide context for data-quality assessment.

---

31. Data Validation

Before a session is treated as usable research data, basic validation can check:

Does session_id exist?

Does session_start exist?

Does session_end or a termination status exist?

Are timestamps ordered?

Is expected trajectory data present?

Were critical sensors operational?

Are coordinates within expected room bounds?

This can eventually become an automated validation stage.

System Architecture

Left → Right

Validation should flag potential issues rather than silently rewriting the original records.

---

32. Data Quality Status

A useful extension is to distinguish session completion from data quality.

For example:

session_status = completed
data_quality = review

A visitor may have completed the experience while one sensor temporarily lost tracking.

Similarly:

session_status = aborted
data_quality = valid

may represent an accurately recorded incomplete experience.

These concepts answer different questions and should not necessarily be collapsed into one status field.

---

33. Logging Without Blocking the Experience

Research logging should not unnecessarily interrupt real-time interaction.

A useful separation is:

System Architecture

Left → Right

The experience and logger consume the same processed information.

Where possible, computationally expensive analysis should occur after the session rather than inside the real-time interaction loop.

This reduces the risk that research instrumentation degrades experience performance.

---

34. Local-First Logging

Responsive installations may operate on local networks without reliable internet access.

Research logging can therefore be designed local-first.

System Architecture

Left → Right

During operation, the installation does not need a cloud connection for every interaction.

Data can be:

1. written locally
2. validated
3. backed up
4. transferred to research storage

This reduces dependence on external connectivity during data collection.

---

35. Backup Strategy

Research data should not exist in only one location.

A simple workflow can be:

LIVE DATA
local machine
     ↓
DAILY COPY
secondary storage
     ↓
VERIFIED BACKUP
research archive

For a temporary study, a daily backup procedure may be sufficient.

For permanent or long-running deployments, automated synchronization may be more appropriate.

The backup strategy should be established before data collection begins.

---

36. Privacy by Architecture

Spatial tracking does not automatically require storing personal identity.

A system can often analyze:

trajectory
dwell
interaction count
area transitions

using an anonymous session identifier.

For example:

S0042

rather than:

visitor_name

Where personal information is collected through check-in, consent procedures, or questionnaires, it can be stored separately and linked only when required by the approved study design.

This reduces unnecessary coupling between behavioural data and personal identity.

---

37. Data Minimization

The fact that a sensor can record information does not mean the research system should retain all of it.

A logging design should ask:

• Is this field necessary for the research question?
• Is this sampling rate necessary?
• Does this information contain unnecessary personal detail?
• How long does this data need to be retained?
• Can a derived representation answer the same question?

Data minimization is both a methodological and system-design consideration.

---

38. Raw and Diagnostic Data Preservation

Processed research data may be sufficient for most analysis.

However, selected lower-level information can be useful when:

• validating tracking
• debugging calibration
• comparing processing algorithms
• reprocessing sessions later

A broader storage architecture may therefore distinguish:

RAW / DIAGNOSTIC
PROCESSED
EVENTS
STUDY INSTRUMENTS

For example:

research_data/
│
├── core/
│   ├── sessions/
│   ├── trajectories/
│   ├── events/
│   └── system/
│
├── raw/
│   └── selected_sensor_data/
│
├── study/
│   ├── questionnaires/
│   ├── observations/
│   └── conditions/
│
└── derived/
    ├── dwell/
    ├── trajectories/
    └── heatmaps/

Not every deployment needs to retain full raw sensor streams.

Storage decisions should follow the research requirements.

---

39. The Complete Data Architecture

The complete research architecture can now be represented as:

System Architecture

Left → Right

This separates four concerns:

1. experience response
2. primary behavioural observations
3. study-specific evidence
4. derived analysis

The architecture allows them to remain connected without becoming one monolithic system.

---

40. Canonical CSWORKS Research Data Model

The broader CSWORKS research model can be summarized as:

SESSION
│
├── PRIMARY OBSERVATIONS
│   ├── Trajectory
│   ├── Interaction Events
│   ├── Scene Events
│   └── System Events
│
├── STUDY-SPECIFIC INSTRUMENTS
│   ├── Questionnaire
│   ├── Interview
│   ├── Observation
│   └── Experimental Conditions
│
└── DERIVED METRICS
    ├── Session Duration
    ├── Dwell Time
    ├── Interaction Count
    ├── Area Visit Count
    ├── Trajectory Length
    ├── Spatial Heatmap
    └── Dwell Heatmap

The session provides the common reference.

Primary observations preserve what occurred.

Study instruments provide additional evidence.

Derived metrics are calculated from the observations.

Research analysis interprets these sources in relation to the research question.

---

41. Relationship to K01–K03

The first four Knowledge articles now describe a continuous architecture.

K01 — Modular Sensor Server Architecture

How should sensing infrastructure be separated?

K02 — Scene-Based Interaction

How should interaction meaning control experience behaviour?

K03 — Raw Sensor Data to Interaction Data

How do sensor measurements become meaningful spatial information?

K04 — Spatial Interaction Logging & Session Architecture

How should meaningful observations be preserved for research?

Together:

System Architecture

Left → Right

This creates a complete path from physical sensing to both responsive experience and research evidence.

---

42. Application to Repeated Deployments

A consistent logging architecture becomes particularly valuable when research infrastructure is reused across several installations.

For example:

Deployment A
→ Core Schema
→ Deployment A Extensions

Deployment B
→ Core Schema
→ Deployment B Extensions

Deployment C
→ Core Schema
→ Deployment C Extensions

The experiences may differ while retaining common variables such as:

session_id
timestamp
x
y
area
event_type

This can make cross-deployment analysis possible where the measurements remain operationally comparable.

Deployment-specific fields can still be added without redefining the entire logging model.

---

43. Versioning

A research infrastructure can evolve over time.

Changes may include:

• sensor configuration
• area definitions
• tracking algorithm
• event vocabulary
• sampling rate
• logging software
• room configuration

A dataset should therefore preserve enough configuration information to identify which system produced it.

For example:

system_version = 1.0.0

More detailed configuration may be stored separately:

configuration_id = FL-FAM-V1

This becomes particularly important when comparing data collected across different dates or deployments.

---

44. Reproducible Metric Definitions

The meaning of derived metrics should also be documented.

For example:

AREA DWELL TIME

Start:
confirmed area_enter timestamp

End:
corresponding area_exit timestamp

Unit:
seconds

Similarly:

INTERACTION COUNT

Definition:
number of interaction_complete events
within one session

This prevents later analysis from changing the meaning of a metric without documentation.

The schema therefore defines not only column names but also the operational meaning of the resulting measures.

---

45. From Logging Architecture to Research Method

Once the architecture is stable, the technical system becomes part of the research method.

For example:

Sensor Infrastructure
        ↓
Spatial Processing
        ↓
Primary Observation
        ↓
Operational Metric
        ↓
Research Analysis

This chain should remain traceable.

If a paper reports:

mean dwell time

it should be possible to determine:

which sensor observations
↓
produced which events
↓
using which dwell definition
↓
under which system version

This traceability strengthens the methodological role of the responsive environment as a research instrument.

---

46. Research Direction

The logging architecture raises methodological questions beyond implementation.

Examples include:

• What sampling resolution is sufficient to characterize spatial behaviour?
• How should a session be defined in multi-user environments?
• Which interaction events remain comparable across different installations?
• How should incomplete sessions be treated?
• How can system failures be distinguished from visitor behaviour?
• How can quantitative spatial logs be combined with qualitative evidence?
• Which measures remain meaningful across changing room configurations?
• How should sensing and logging systems evolve without invalidating longitudinal comparisons?

A broader question emerges:

How can responsive environments become reliable research instruments without allowing data collection requirements to dominate the experience itself?

This connects system architecture, HCI methodology, and spatial interaction research.

---

47. Key Takeaways

A research-ready responsive environment needs more than sensor data.

It needs a structured relationship between:

Session → Time → Spatial Observation → Interaction Event → Experience State → Research Record

The architecture should distinguish three major research-data layers:

Primary Observations

What the system directly records:

trajectory samples
interaction events
scene events
system events

Study-Specific Instruments

Additional evidence required by a particular study:

questionnaires
interviews
observations
experimental conditions

Derived Metrics

Measurements calculated from primary observations:

dwell time
interaction count
trajectory length
heatmaps
scene duration

A shared session_id provides the common reference across these layers.

This creates a reusable logging foundation that can support different responsive environments while allowing each research study to extend the system according to its own methodological requirements.

The broader principle is:

Preserve primary observations in a stable session-based structure, derive analytical measures explicitly, and keep study-specific instruments separate from the core sensing infrastructure.