Skip to content

Commit 86485f9

Browse files
kfarrkfarr
committed
v1 managed-street docs
1 parent 3f08aad commit 86485f9

File tree

7 files changed

+523
-0
lines changed

7 files changed

+523
-0
lines changed

‎docs/managed-street/_category_.json

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"label": "Managed Street (Beta)",
3+
"position": 4,
4+
"link": {
5+
"type": "generated-index",
6+
"description": "A collection of documentation for Managed Street format and UI."
7+
}
8+
}

‎docs/managed-street/component-managed-street.md

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
sidebar_position: 2
3+
---
4+
5+
# `managed-street` Component
6+
7+
The `managed-street` component manages the creation, updating, and synchronization of one or more `street-segment`s in a 3D environment. It provides a high-level interface for handling street layouts, including support for importing from various data sources and managing street segments.
8+
9+
### User Interface
10+
11+
A custom sidebar in 3DStreet Editor allows users to edit a subset of `managed-street` component properties.
12+
13+
* Street Length: Users can modify the overall length of the street through a numeric input field. This change is propagated to all segments simultaneously.
14+
* Labels: A toggle control to enable or disable street labels for better visualization and identification of segments.
15+
16+
![Managed Street Sidebar](/img/docs/managed-street/managed-street-ui-sidebar.png)
17+
18+
19+
### Properties
20+
21+
| Property | Type | Default | Description |
22+
|-------------|-----------|---------|-------------|
23+
| length | number | 60 | The length of the street in meters |
24+
| sourceType | string | null | The type of source data (`streetmix-url`, `streetplan-url`, or `json-blob`) |
25+
| sourceValue | string | null | The value corresponding to the sourceType (URL or JSON string) |
26+
| synchronize | boolean | false | When set to true, triggers a refresh from the source |
27+
28+
### Dependencies
29+
30+
This component automatically adds the following components if they don't exist:
31+
- `street-align`
32+
- `street-ground`
33+
- `street-label`
34+
35+
### Events
36+
37+
| Event Name | Description | Event Detail |
38+
|------------|-------------|--------------|
39+
| segments-changed | Fired when segments are added, removed, or modified | `{changeType, property?, segment?, oldValue?, newValue?, added?, removed?}` |
40+
41+
### Methods
42+
43+
#### insertSegment(index, type, segmentObject)
44+
45+
Inserts a new street segment at the specified index.
46+
47+
```javascript
48+
// Example
49+
const street = document.querySelector('[managed-street]');
50+
street.components['managed-street'].insertSegment(0, 'drive-lane', {
51+
width: 3,
52+
level: 0,
53+
direction: 'outbound',
54+
color: '#FFFFFF',
55+
surface: 'asphalt'
56+
});
57+
```
58+
59+
Parameters:
60+
- `index` (number): The position to insert the segment
61+
- `type` (string): The segment type (e.g., 'drive-lane', 'bike-lane')
62+
- `segmentObject` (object, optional): Configuration object for the segment
63+
64+
#### refreshFromSource()
65+
66+
Reloads and parses data from the specified source.
67+
68+
```javascript
69+
const street = document.querySelector('[managed-street]');
70+
street.components['managed-street'].refreshFromSource();
71+
```
72+
73+
### Data Source Support
74+
75+
#### Streetmix URL
76+
77+
Supports importing street layouts from Streetmix URLs:
78+
79+
```html
80+
<a-entity managed-street="sourceType: streetmix-url; sourceValue: https://streetmix.net/..."></a-entity>
81+
```
82+
83+
#### Streetplan URL
84+
85+
Supports importing street layouts from Streetplan JSON URLs:
86+
87+
```html
88+
<a-entity managed-street="sourceType: streetplan-url; sourceValue: https://..."></a-entity>
89+
```
90+
91+
#### JSON Blob
92+
93+
Supports direct JSON configuration:
94+
95+
```html
96+
<a-entity managed-street="sourceType: json-blob; sourceValue: '{...}'"></a-entity>
97+
```
98+
99+
### JSON Schema
100+
101+
The component expects street data in the following format:
102+
103+
```javascript
104+
{
105+
name: string, // Name of the street
106+
width: number, // Total width in meters
107+
length: number, // Length in meters
108+
segments: [{ // Array of segment objects
109+
type: string, // Segment type (e.g., 'drive-lane')
110+
width: number, // Width in meters
111+
name: string, // Display name
112+
level: number, // Vertical offset (0 or 1)
113+
direction: string, // 'inbound', 'outbound', or 'none'
114+
color: string, // Hex color code
115+
surface: string, // Surface type (e.g., 'asphalt')
116+
generated?: { // Optional generated content
117+
striping?: array, // Striping configurations
118+
clones?: array // Clone configurations
119+
}
120+
}]
121+
}
122+
```
123+
124+
125+
### Notes
126+
127+
- The component automatically handles the positioning and alignment of segments
128+
- Segments are automatically centered around the x-axis
129+
- Width calculations are performed in meters
130+
- The component maintains internal state of managed entities for performance
131+
132+
### Known Limitations
133+
134+
- Source URLs must be accessible and return valid JSON
135+
- Some segment types may have limited support for certain features
136+
- The component is currently in beta and APIs may change

‎docs/managed-street/component-street-segment.md

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
---
2+
sidebar_position: 3
3+
---
4+
5+
# `street-segment` Component
6+
7+
The `street-segment` component creates and manages individual street segments in a 3D environment. Each segment represents a distinct part of the street (e.g., drive lanes, bike lanes, sidewalks) with specific properties and behaviors.
8+
9+
## User Interface
10+
11+
A custom sidebar in 3DStreet Editor allows users to edit a subset of `street-segment` properties and associated generated components.
12+
13+
![Street Segment Sidebar](/img/docs/managed-street/street-segment-ui-sidebar.png)
14+
15+
## Properties
16+
17+
| Property | Type | Default | Description |
18+
|------------|--------|----------|-------------|
19+
| type | string | - | Type of street segment. Must be one of: 'drive-lane', 'bus-lane', 'bike-lane', 'sidewalk', 'parking-lane', 'divider', 'grass', 'rail' |
20+
| width | number | - | Width of the segment in meters |
21+
| length | number | - | Length of the segment in meters |
22+
| level | int | 0 | Vertical level of the segment (-1 to 2) |
23+
| direction | string | - | Direction of traffic flow: 'none', 'inbound', or 'outbound' |
24+
| surface | string | 'asphalt'| Surface material type. One of: 'asphalt', 'concrete', 'grass', 'sidewalk', 'gravel', 'sand', 'none', 'solid' |
25+
| color | color | - | Color of the segment surface |
26+
27+
## Segment Types
28+
29+
The component includes several predefined segment types with specific configurations:
30+
31+
### Drive Lane
32+
```javascript
33+
{
34+
type: 'drive-lane',
35+
color: white,
36+
surface: 'asphalt',
37+
level: 0,
38+
generated: {
39+
clones: [{
40+
mode: 'random',
41+
modelsArray: 'sedan-rig, box-truck-rig, self-driving-waymo-car, suv-rig, motorbike',
42+
spacing: 7.3,
43+
count: 4
44+
}]
45+
}
46+
}
47+
```
48+
49+
### Bus Lane
50+
```javascript
51+
{
52+
type: 'bus-lane',
53+
surface: 'asphalt',
54+
color: red,
55+
level: 0,
56+
generated: {
57+
clones: [{ mode: 'random', modelsArray: 'bus', spacing: 15, count: 1 }],
58+
stencil: [{ modelsArray: 'word-only, word-taxi, word-bus', spacing: 40, padding: 10 }]
59+
}
60+
}
61+
```
62+
63+
### Bike Lane
64+
```javascript
65+
{
66+
type: 'bike-lane',
67+
color: green,
68+
surface: 'asphalt',
69+
level: 0,
70+
generated: {
71+
stencil: [{ modelsArray: 'bike-arrow', cycleOffset: 0.3, spacing: 20 }],
72+
clones: [{
73+
mode: 'random',
74+
modelsArray: 'cyclist-cargo, cyclist1, cyclist2, cyclist3, cyclist-dutch, cyclist-kid, ElectricScooter_1',
75+
spacing: 2.03,
76+
count: 4
77+
}]
78+
}
79+
}
80+
```
81+
82+
## Events
83+
84+
| Event Name | Description | Event Detail |
85+
|------------|-------------|--------------|
86+
| segment-width-changed | Fired when segment width is modified | `{oldWidth, newWidth}` |
87+
88+
## Generated Components
89+
90+
The component can automatically generate and manage several sub-components based on the segment type:
91+
92+
- **Clones**: Generates repeated 3D models (vehicles, cyclists, etc.)
93+
- **Stencils**: Adds road markings and symbols
94+
- **Pedestrians**: Adds pedestrian models with configurable density
95+
- **Striping**: Adds road stripes and markings
96+
97+
## Surface Types and Textures
98+
99+
The component supports various surface types with corresponding textures:
100+
101+
| Surface Type | Texture ID | Description |
102+
|--------------|------------|-------------|
103+
| asphalt | seamless-road | Standard road surface |
104+
| concrete | seamless-bright-road | Bright concrete surface |
105+
| grass | grass-texture | Grass surface |
106+
| sidewalk | seamless-sidewalk | Sidewalk texture |
107+
| gravel | compacted-gravel-texture | Gravel surface |
108+
| sand | sandy-asphalt-texture | Sandy surface |
109+
| hatched | hatched-base | Hatched marking pattern |
110+
111+
## Usage
112+
113+
Basic usage example:
114+
115+
```html
116+
<a-entity street-segment="
117+
type: drive-lane;
118+
surface: asphalt;
119+
color: white;
120+
width: 3;
121+
length: 150">
122+
</a-entity>
123+
```
124+
125+
## Component Lifecycle
126+
127+
The component manages several key operations during its lifecycle:
128+
129+
1. **Initialization**: Sets up default height and generated components list
130+
2. **Update**: Handles property changes and updates meshes accordingly
131+
3. **Remove**: Cleans up generated components and meshes
132+
133+
## Methods
134+
135+
### calculateHeight(elevationLevel)
136+
Converts elevation levels (-1 to 2) to Three.js meter units.
137+
138+
### generateMesh(data)
139+
Creates the segment's 3D geometry and materials.
140+
141+
### calculateTextureRepeat(length, width, textureSourceId)
142+
Calculates texture repeat and offset values based on segment dimensions.
143+
144+
## Notes
145+
146+
- The component automatically handles elevation changes based on the level property
147+
- Texture repeats are calculated automatically based on segment dimensions
148+
- Generated components (vehicles, pedestrians, etc.) are managed automatically based on segment type
149+
- The component uses a custom 'below-box' geometry for proper ground alignment
150+
151+
## Known Limitations
152+
153+
- Surface textures must be present via asset loader, this component does not preload textures
154+
- Some generated components require specific 3D models to be available
155+
- Elevation levels are limited to the range of -1 to 2

0 commit comments

Comments
 (0)