@mark1russell7/visuals 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,9 +2,10 @@
2
2
 
3
3
  3D stages for data. A stage is one canvas of three.js with a camera that a person moves. The content of the stage is your data.
4
4
 
5
- The package has three entries:
5
+ The package has four entries:
6
6
 
7
- - The entry `.` has the camera maths: views, places, moves, keys and marks. It needs no browser, and it does not need `three`.
7
+ - The entry `.` has the camera maths: views, places, moves, keys and highlights. It needs no browser, and it does not need `three`.
8
+ - The entry `/marks` has the marks that a viewer draws, as plain data. It needs no browser, and it does not need `three`.
8
9
  - The entry `/three` has the stage. It needs the package `three`, version 0.187.0 or later.
9
10
  - The entry `/globe` has a content that shows the Earth as a globe, with areas and points on it. It also needs `three`.
10
11
 
@@ -14,6 +15,8 @@ The package has three entries:
14
15
  npm install @mark1russell7/visuals three
15
16
  ```
16
17
 
18
+ A package that uses only the entries `.` and `/marks` does not install `three`.
19
+
17
20
  ## A stage
18
21
 
19
22
  ```ts
@@ -32,7 +35,7 @@ const content: StageContent<string> = {
32
35
  },
33
36
  has: (record) => record === "box",
34
37
  pick: (ray) => (ray.intersectObject(box).length > 0 ? { record: "box", value: "the box" } : undefined),
35
- paint: (_theme, mark) => void material.color.set(mark("box") === 0 ? "#4f7cac" : "#e0a03a"),
38
+ paint: (_theme, highlight) => void material.color.set(highlight("box") === 0 ? "#4f7cac" : "#e0a03a"),
36
39
  dispose: () => {
37
40
  box.geometry.dispose();
38
41
  material.dispose();
@@ -71,11 +74,11 @@ A stage knows nothing about the data. The content gives it these parts:
71
74
  | `objects` | The three.js objects of the content. |
72
75
  | `extent` | The space that the content fills: the point that the camera looks at, and the corners that a view shows. |
73
76
  | `pick` | The record that a ray from the camera finds first. |
74
- | `paint` | The colors of each part, from the theme and the mark of its record. |
77
+ | `paint` | The colors of each part, from the theme and the highlight of its record. |
75
78
  | `step` | The parts that change with the camera or with the time, before each picture. It is optional. |
76
79
  | `dispose` | The release of the memory of the graphics card. |
77
80
 
78
- A record has a name. The mark of a record is 0, 1 or 2: no mark, a record under the pointer, the selected record. `highlight` and `select` set the marks from the page.
81
+ A record has a name. The highlight of a record is 0, 1 or 2: no highlight, a record under the pointer, the selected record. `highlight` and `select` set the highlights from the page.
79
82
 
80
83
  ## Views
81
84
 
@@ -202,6 +205,57 @@ surface.corners.length / 2; // => 43: the corners of the outline with a step of
202
205
  surface.triangles.length / 3; // => 70
203
206
  ```
204
207
 
208
+ ## The marks
209
+
210
+ A mark is a record that a viewer draws. A mark is plain data with no topic, so each viewer draws the marks of each producer.
211
+
212
+ ```ts
213
+ import { checkMarks, levelShape, shapeRing, type Mark } from "@mark1russell7/visuals/marks";
214
+
215
+ const marks: readonly Mark[] = [
216
+ {
217
+ type: "point",
218
+ record: "outlet-1",
219
+ kind: "outlet",
220
+ level: "near",
221
+ label: "Outlet 1",
222
+ frame: { at: { x: 1, y: 0, z: 0.3 }, out: { x: 0, y: 1, z: 0 } },
223
+ },
224
+ { type: "meter", record: "circuit-1", kind: "circuit", level: "over", label: "Circuit 1", value: 1900, limit: 1440, unit: "W" },
225
+ ];
226
+
227
+ checkMarks(marks); // => []: the list has no fault
228
+ levelShape("near"); // => "triangle"
229
+ shapeRing("triangle").length; // => 3: the corners of the sign, counter-clockwise
230
+ ```
231
+
232
+ | Mark | Data | Example |
233
+ | --- | --- | --- |
234
+ | `point` | A frame and a size | An outlet, a tap, a lamp |
235
+ | `run` | A list of frames and a width | A cable, a pipe, a duct |
236
+ | `link` | Two ends, each with a record name and a point | A power line from an outlet to a computer |
237
+ | `field` | A grid of values on a plane, and a scale | Light in lux, sound in decibels, heat |
238
+ | `meter` | A value, a limit and the text of the unit | The load of a circuit against its limit |
239
+
240
+ - Each mark has a record name, a kind, a level and a label. The kind is a word of the producer for the legend and the filter.
241
+ - A frame is a point of a surface and the unit vector out of the surface.
242
+ - The level of a mark is `unknown`, `ok`, `near` or `over`. The producer calculates it, because each topic has its own limits.
243
+ - A mark has no shape and no color. `levelShape` gives each level its shape, and the theme of a viewer gives its color.
244
+ - Thus a person who does not see a color reads the level from the shape: a ring, a disc, a triangle or a square.
245
+ - A viewer draws the marks in the sequence of `levelRank`, so the worst level is always in view.
246
+ - A field has its values row by row, with `null` for a cell with no value. `fieldValue` and `fieldCellCenter` read a cell.
247
+ - A meter has no place. A page draws it in a panel, and a 3D view ignores it.
248
+ - Each point of a list of marks is in one space. The producer tells the unit and the axes of that space.
249
+
250
+ `checkMarks` gives the faults of a list, each with a code, the index of its mark and the part with the fault. It examines the values that the types do not hold:
251
+
252
+ - A number that is not finite, and a direction that is not a unit vector.
253
+ - A size, a width or a cell that is not more than 0.
254
+ - The grid, the values and the scale of a field, and a run with fewer than 2 points.
255
+ - An empty name, an empty label, and a level or a type that is not known.
256
+
257
+ Use it as a gate in the tests of a producer. A viewer uses it on a list that it did not make. It does not examine the form of a mark, so read a list from JSON through a schema first.
258
+
205
259
  ## The camera maths
206
260
 
207
261
  The entry `.` has pure functions. A page with no WebGL 2 and a test in Node.js use the same functions as the stage.
@@ -216,7 +270,7 @@ The entry `.` has pure functions. A page with no WebGL 2 and a test in Node.js u
216
270
  | `clampPlace`, `stageLimits` | A place in the limits of a stage, and the limits from the content. |
217
271
  | `reachOf`, `nearDepth` | The radius of the ball that holds the content, and the nearest depth that the camera draws. |
218
272
  | `keyAction` | The action of a key. |
219
- | `markOf`, `isClick` | The mark of a record, and the difference between a click and a drag. |
273
+ | `highlightOf`, `isClick` | The highlight of a record, and the difference between a click and a drag. |
220
274
  | `approach` | One step of a value to its goal, for a part that changes with time. |
221
275
 
222
276
  The space of a stage has the y axis up. A place has a target, a polar angle from the y axis, an azimuth around it and a distance.
package/build/globe.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { i as StageContent } from "./stage-C9NHD-6Q.js";
2
- import { S as ViewAngles, d as StageView, t as StageTheme } from "./theme-CJ2SAcHX.js";
1
+ import { i as StageContent } from "./stage-CtWLSoV-.js";
2
+ import { S as ViewAngles, d as StageView, t as StageTheme } from "./theme-CKXd_emk.js";
3
3
  import { Raycaster } from "three";
4
4
  import { LatLon, Region } from "@mark1russell7/geo";
5
5
  import { Point3 } from "@mark1russell7/layout-contract";
@@ -24,14 +24,14 @@ interface GlobeTheme extends StageTheme {
24
24
  readonly styles: Readonly<Record<string, GlobeStyle>>;
25
25
  /** The style of a kind that `styles` does not have. */
26
26
  readonly other: GlobeStyle;
27
- /** The color of the edge of a record under the pointer, or in the marked list. */
27
+ /** The color of the edge of a record under the pointer, or in the highlighted list. */
28
28
  readonly hovered: string;
29
29
  /** The color of the edge of the selected record. */
30
30
  readonly selected: string;
31
31
  }
32
32
  /** An area of a globe: a region of the Earth that belongs to a record. */
33
33
  interface GlobeArea<P> {
34
- /** The name of the record. Two parts with one name are one record: the stage marks them together. */
34
+ /** The name of the record. Two parts with one name are one record: the stage highlights them together. */
35
35
  readonly record: string;
36
36
  /** The region, with edges that are straight lines in longitude and latitude, as in `@mark1russell7/geo`. */
37
37
  readonly region: Region;
@@ -44,7 +44,7 @@ interface GlobeArea<P> {
44
44
  }
45
45
  /** A point of a globe: a place on the Earth that belongs to a record. The picture shows it as a dot of a constant size. */
46
46
  interface GlobePoint<P> {
47
- /** The name of the record. Two parts with one name are one record: the stage marks them together. */
47
+ /** The name of the record. Two parts with one name are one record: the stage highlights them together. */
48
48
  readonly record: string;
49
49
  readonly place: LatLon;
50
50
  /** The name of the style of the point in the theme. */
@@ -72,8 +72,8 @@ interface GlobeOptions<P> {
72
72
  readonly nearest?: number | undefined;
73
73
  /** The width of the edge of an area. The default is 1.25. */
74
74
  readonly lineWidth?: number | undefined;
75
- /** The width of the edge of a record with a mark. The default is 2.5. */
76
- readonly markWidth?: number | undefined;
75
+ /** The width of the edge of a record with a highlight. The default is 2.5. */
76
+ readonly highlightWidth?: number | undefined;
77
77
  /** The width of a line of the grid. The default is 1. */
78
78
  readonly gridWidth?: number | undefined;
79
79
  /** The width of the dot of a point. The default is 9. */
package/build/globe.js CHANGED
@@ -557,10 +557,10 @@ function inSight(point, eye, radius) {
557
557
  // src/globe/content.ts
558
558
  /** The smallest height of the layer of the areas above the ball, as a part of the radius. */
559
559
  const MIN_LIFT = 5e-4;
560
- /** The opacity that a mark adds to the surface of an area. */
561
- const MARK_OPACITY = .16;
562
- /** The factor of the width of a point with a mark. */
563
- const MARK_SIZE = 1.35;
560
+ /** The opacity that a highlight adds to the surface of an area. */
561
+ const HIGHLIGHT_OPACITY = .16;
562
+ /** The factor of the width of a point with a highlight. */
563
+ const HIGHLIGHT_SIZE = 1.35;
564
564
  /** The width of the ring around a point, in CSS pixels. */
565
565
  const RING_WIDTH = 1.5;
566
566
  /** The distance around a point where the pointer finds it, in CSS pixels. */
@@ -724,7 +724,7 @@ function createGlobe(options = {}) {
724
724
  shown: true,
725
725
  filled: false,
726
726
  lined: false,
727
- mark: 0
727
+ highlight: 0
728
728
  });
729
729
  surfaces.push(surface);
730
730
  cornerTotal += surface.corners.length / 2;
@@ -781,16 +781,16 @@ function createGlobe(options = {}) {
781
781
  const edges = new LineSegments2(edgeGeometry, edgeMaterial);
782
782
  edges.renderOrder = 3;
783
783
  edges.frustumCulled = false;
784
- const markMaterial = new LineMaterial({
785
- linewidth: options.markWidth ?? 2.5,
784
+ const highlightMaterial = new LineMaterial({
785
+ linewidth: options.highlightWidth ?? 2.5,
786
786
  vertexColors: true,
787
787
  transparent: true,
788
788
  depthWrite: false
789
789
  });
790
- const marked = new LineSegments2(new LineSegmentsGeometry(), markMaterial);
791
- marked.renderOrder = 5;
792
- marked.frustumCulled = false;
793
- marked.visible = false;
790
+ const highlighted = new LineSegments2(new LineSegmentsGeometry(), highlightMaterial);
791
+ highlighted.renderOrder = 5;
792
+ highlighted.frustumCulled = false;
793
+ highlighted.visible = false;
794
794
  const pointSize = options.pointSize ?? 9;
795
795
  const pointParts = (options.points ?? []).map((point) => ({
796
796
  point,
@@ -798,7 +798,7 @@ function createGlobe(options = {}) {
798
798
  size: point.size ?? pointSize,
799
799
  shown: true,
800
800
  filled: false,
801
- mark: 0
801
+ highlight: 0
802
802
  }));
803
803
  const pointPositions = new Float32Array(pointParts.length * 3);
804
804
  pointParts.forEach((part, index) => pointPositions.set([
@@ -839,7 +839,7 @@ function createGlobe(options = {}) {
839
839
  /** The angle of one CSS pixel at the middle of the picture, in radians. */
840
840
  let pixelAngle = .001;
841
841
  const styleOf = (theme, kind) => theme.styles[kind] ?? theme.other;
842
- const markColor = (theme, mark) => mark === 2 ? theme.selected : theme.hovered;
842
+ const highlightColor = (theme, highlight) => highlight === 2 ? theme.selected : theme.hovered;
843
843
  /** This function writes the colors of an area into the buffers. */
844
844
  const paintArea = (part, theme) => {
845
845
  const style = styleOf(theme, part.area.kind);
@@ -848,7 +848,7 @@ function createGlobe(options = {}) {
848
848
  if (style.fill !== void 0) {
849
849
  color.set(style.fill);
850
850
  const opacity = Math.min(Math.max(style.opacity ?? 1, 0), 1);
851
- const alpha = part.mark === 0 ? opacity : Math.min(opacity + MARK_OPACITY, 1);
851
+ const alpha = part.highlight === 0 ? opacity : Math.min(opacity + HIGHLIGHT_OPACITY, 1);
852
852
  const values = [
853
853
  color.r,
854
854
  color.g,
@@ -875,7 +875,7 @@ function createGlobe(options = {}) {
875
875
  const sync = (theme) => {
876
876
  let indexCount = 0;
877
877
  let segmentCount = 0;
878
- let markCount = 0;
878
+ let highlightCount = 0;
879
879
  for (const part of areaParts) {
880
880
  if (!part.shown) continue;
881
881
  if (part.filled) {
@@ -889,7 +889,7 @@ function createGlobe(options = {}) {
889
889
  edgeColors.array.set(allSegmentColors.subarray(from, to), segmentCount * 6);
890
890
  segmentCount += part.segmentCount;
891
891
  }
892
- if (part.mark !== 0) markCount += part.segmentCount;
892
+ if (part.highlight !== 0) highlightCount += part.segmentCount;
893
893
  }
894
894
  fillIndices.needsUpdate = true;
895
895
  fillGeometry.setDrawRange(0, indexCount);
@@ -898,12 +898,12 @@ function createGlobe(options = {}) {
898
898
  edgeColors.needsUpdate = true;
899
899
  edgeGeometry.instanceCount = segmentCount;
900
900
  edges.visible = segmentCount > 0;
901
- const markPositions = new Float32Array(markCount * 6);
902
- const markColors = new Float32Array(markCount * 6);
901
+ const highlightPositions = new Float32Array(highlightCount * 6);
902
+ const highlightColors = new Float32Array(highlightCount * 6);
903
903
  let at = 0;
904
904
  for (const part of areaParts) {
905
- if (!part.shown || part.mark === 0) continue;
906
- color.set(markColor(theme, part.mark));
905
+ if (!part.shown || part.highlight === 0) continue;
906
+ color.set(highlightColor(theme, part.highlight));
907
907
  const values = [
908
908
  color.r,
909
909
  color.g,
@@ -912,18 +912,18 @@ function createGlobe(options = {}) {
912
912
  color.g,
913
913
  color.b
914
914
  ];
915
- markPositions.set(allSegments.subarray(part.firstSegment * 6, (part.firstSegment + part.segmentCount) * 6), at * 6);
916
- for (let segment = 0; segment < part.segmentCount; segment++) markColors.set(values, (at + segment) * 6);
915
+ highlightPositions.set(allSegments.subarray(part.firstSegment * 6, (part.firstSegment + part.segmentCount) * 6), at * 6);
916
+ for (let segment = 0; segment < part.segmentCount; segment++) highlightColors.set(values, (at + segment) * 6);
917
917
  at += part.segmentCount;
918
918
  }
919
- marked.geometry.dispose();
920
- marked.geometry = markCount > 0 ? segmentGeometry(new InstancedInterleavedBuffer(markPositions, 6, 1), new InstancedInterleavedBuffer(markColors, 6, 1), markCount, bounds) : new LineSegmentsGeometry();
921
- marked.visible = markCount > 0;
919
+ highlighted.geometry.dispose();
920
+ highlighted.geometry = highlightCount > 0 ? segmentGeometry(new InstancedInterleavedBuffer(highlightPositions, 6, 1), new InstancedInterleavedBuffer(highlightColors, 6, 1), highlightCount, bounds) : new LineSegmentsGeometry();
921
+ highlighted.visible = highlightCount > 0;
922
922
  pointParts.forEach((part, index) => {
923
923
  const style = styleOf(theme, part.point.kind);
924
924
  part.filled = style.fill !== void 0;
925
925
  const visible = part.shown && style.fill !== void 0;
926
- pointSizes.array[index] = visible ? part.size * (part.mark === 0 ? 1 : MARK_SIZE) : 0;
926
+ pointSizes.array[index] = visible ? part.size * (part.highlight === 0 ? 1 : HIGHLIGHT_SIZE) : 0;
927
927
  if (style.fill === void 0) return;
928
928
  color.set(style.fill);
929
929
  pointFills.array.set([
@@ -931,7 +931,7 @@ function createGlobe(options = {}) {
931
931
  color.g,
932
932
  color.b
933
933
  ], index * 3);
934
- color.set(part.mark === 0 ? style.line ?? style.fill : markColor(theme, part.mark));
934
+ color.set(part.highlight === 0 ? style.line ?? style.fill : highlightColor(theme, part.highlight));
935
935
  pointRings.array.set([
936
936
  color.r,
937
937
  color.g,
@@ -949,7 +949,7 @@ function createGlobe(options = {}) {
949
949
  fills,
950
950
  edges,
951
951
  shade,
952
- marked,
952
+ highlighted,
953
953
  dots
954
954
  ],
955
955
  extent: {
@@ -994,7 +994,7 @@ function createGlobe(options = {}) {
994
994
  };
995
995
  }
996
996
  },
997
- paint(theme, mark) {
997
+ paint(theme, highlight) {
998
998
  const all = theme !== painted;
999
999
  painted = theme;
1000
1000
  if (all) {
@@ -1003,12 +1003,12 @@ function createGlobe(options = {}) {
1003
1003
  shadeColor.value.set(theme.shade);
1004
1004
  }
1005
1005
  for (const part of areaParts) {
1006
- const next = mark(part.area.record);
1007
- if (!all && next === part.mark) continue;
1008
- part.mark = next;
1006
+ const next = highlight(part.area.record);
1007
+ if (!all && next === part.highlight) continue;
1008
+ part.highlight = next;
1009
1009
  paintArea(part, theme);
1010
1010
  }
1011
- for (const part of pointParts) part.mark = mark(part.point.record);
1011
+ for (const part of pointParts) part.highlight = highlight(part.point.record);
1012
1012
  sync(theme);
1013
1013
  },
1014
1014
  step(frame) {
@@ -1034,8 +1034,8 @@ function createGlobe(options = {}) {
1034
1034
  fillMaterial.dispose();
1035
1035
  edgeGeometry.dispose();
1036
1036
  edgeMaterial.dispose();
1037
- marked.geometry.dispose();
1038
- markMaterial.dispose();
1037
+ highlighted.geometry.dispose();
1038
+ highlightMaterial.dispose();
1039
1039
  pointGeometry.dispose();
1040
1040
  pointMaterial.dispose();
1041
1041
  }