@citolab/pci-3d-blocks 1.1.0 → 1.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
|
@@ -1,32 +1,84 @@
|
|
|
1
1
|
# @citolab/pci-3d-blocks
|
|
2
2
|
|
|
3
|
-
A QTI 3 Portable Custom Interaction (PCI) in which the candidate builds with toy bricks on a baseplate,
|
|
4
|
-
building shown in the item. Made with
|
|
3
|
+
A QTI 3 Portable Custom Interaction (PCI) in which the candidate builds with toy bricks on a baseplate, for example to
|
|
4
|
+
recreate a building shown in the item from its front, side and top view. Made with
|
|
5
|
+
[tspci](https://github.com/Citolab/tspci).
|
|
5
6
|
|
|
6
7
|
<p align="center">
|
|
7
8
|
<img src="https://raw.githubusercontent.com/Citolab/tspci-examples/main/tspci-3d-blocks/example.png" alt="Bricks on a baseplate, with the label front" width="320">
|
|
8
9
|
</p>
|
|
9
10
|
|
|
10
|
-
|
|
11
|
-
- The response is the front, side and top view of the build: every build with the same views gives the same response,
|
|
12
|
-
so the item scores with `match_correct`
|
|
13
|
-
- The item author sets the correct response by building it (TAO, qti-construction)
|
|
11
|
+
## What it does
|
|
14
12
|
|
|
15
|
-
|
|
13
|
+
- **Build**: click a cell of the baseplate to place a brick, click the top of a brick to stack one on it. A brick
|
|
14
|
+
shows where it will land before you click.
|
|
15
|
+
- **Remove**: click the side of a brick to take it away (a brick in the top layer goes with any click); the brick that
|
|
16
|
+
would go is shown in see-through red first.
|
|
17
|
+
- **Look around**: drag to turn the baseplate. The arrow and its label mark the front, so the candidate can tell
|
|
18
|
+
front, side and top apart.
|
|
19
|
+
- **Limits**: bricks stay on the plate, and a stack is at most as high as the grid is wide (5 × 5 × 5 by default).
|
|
20
|
+
- **Colours**: a brick's colour follows from where it stands, so a build looks the same when the candidate comes back
|
|
21
|
+
to it. Colours do not count for the answer.
|
|
22
|
+
- **Delivery**: the build is saved as the item's state and restored. In review (`status: "solution"`) the PCI shows the
|
|
23
|
+
correct response when the delivery system passes it.
|
|
16
24
|
|
|
17
|
-
|
|
18
|
-
| ----------------------------- | --------------------------------------------------------------------------- |
|
|
19
|
-
| `dist/index.js` | the PCI (AMD module, everything bundled: the package has no dependencies) |
|
|
20
|
-
| `dist/authoring.json` | settings, response and scoring, for authoring systems |
|
|
21
|
-
| `dist/sbom.cdx.json` | CycloneDX SBOM of the bundle |
|
|
22
|
-
| `dist/tao-pci-blocks_<version>.zip` | the PCI for TAO: Settings → Portable Custom Interactions → Add |
|
|
23
|
-
| `blocks.svg`, `example.png` | icon and screenshot |
|
|
25
|
+
## What can be configured
|
|
24
26
|
|
|
25
|
-
|
|
27
|
+
Every setting is a `data-` attribute of the interaction, as text. `dist/authoring.json` describes them for authoring
|
|
28
|
+
systems; TAO shows them as a form, with a dropdown for the colour mode and colour pickers.
|
|
29
|
+
|
|
30
|
+
| setting | attribute | default | what |
|
|
31
|
+
| -------------------- | ----------------------- | ------------------------------------------------------ | --------------------------------------------------------- |
|
|
32
|
+
| Grid size | `data-grid-divisions` | `5` | cells per side of the baseplate (1 to 6); also the maximum height |
|
|
33
|
+
| Brick size | `data-cube-pixel-size` | `60` | size of a brick (at least 10) |
|
|
34
|
+
| Label at the front | `data-front-label` | `front` | the text under the arrow, for the item's language |
|
|
35
|
+
| Brick colours | `data-brick-color-mode` | `mixed` | `mixed`: the bricks get the colours of the list; `single`: all bricks get the first colour |
|
|
36
|
+
| Colours | `data-brick-colors` | `#c91a09, #f2cd37, #0055bf, #237841, #fe8a18, #5aa5dc` | a list of CSS colours |
|
|
37
|
+
| Baseplate colour | `data-baseplate-color` | `#4b9f4a` | a CSS colour |
|
|
38
|
+
| Width, height | `data-width`, `data-height` | `400`, `400` | size of the interaction in pixels (at least 200) |
|
|
39
|
+
|
|
40
|
+
## Scoring
|
|
41
|
+
|
|
42
|
+
The PCI is made for `match_correct` (`authoring.json`: `"score": ["MATCH_CORRECT", "NONE"]`).
|
|
43
|
+
|
|
44
|
+
**The response** is a string (`cardinality="single" base-type="string"`): the three views of the build, as JSON. Per
|
|
45
|
+
view, every cell of the grid is `found: true` when a brick is seen there.
|
|
46
|
+
|
|
47
|
+
```json
|
|
48
|
+
{ "xPlane": [{ "y": 0, "z": 0, "found": true }, …], "yPlane": [{ "x": 0, "z": 0, "found": false }, …], "zPlane": [{ "x": 0, "y": 0, "found": true }, …] }
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
- **What counts**: only the views. Two builds that look the same from the front, the side and the top give the same
|
|
52
|
+
response, even when bricks inside differ, so there is one correct response for all of them.
|
|
53
|
+
- **What does not count**: colours, the order of building, and how the candidate turned the plate.
|
|
54
|
+
- **Setting the correct response**: answer the PCI. In TAO switch the interaction to *Response* and build the answer;
|
|
55
|
+
in qti-construction or the PCI showcase, build it and take it as the correct response. A string comparison then
|
|
56
|
+
scores it: 1 when the views match, otherwise 0.
|
|
57
|
+
- The views depend on the grid size: change the grid size and set the correct response again.
|
|
58
|
+
- **No response**: until the candidate places a brick, `getResponse()` reports nothing.
|
|
59
|
+
- `NONE`: use the PCI without scoring, for instance as a tool or for a human rater.
|
|
60
|
+
|
|
61
|
+
## Using it
|
|
62
|
+
|
|
63
|
+
```sh
|
|
64
|
+
npm install @citolab/pci-3d-blocks
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
| file | what |
|
|
68
|
+
| ------------------------------------ | ------------------------------------------------------------------------- |
|
|
69
|
+
| `dist/index.js` | the PCI (AMD module, everything bundled: the package has no dependencies) |
|
|
70
|
+
| `dist/authoring.json` | settings, response and scoring, for authoring systems |
|
|
71
|
+
| `dist/sbom.cdx.json` | CycloneDX SBOM of the bundle |
|
|
72
|
+
| `dist/tao-pci-blocks_<version>.zip` | the PCI for TAO: Settings → Portable Custom Interactions → Add |
|
|
73
|
+
| `blocks.svg`, `example.png` | icon and screenshot |
|
|
74
|
+
|
|
75
|
+
In a QTI 3 item, with `index.js` at `resources/pci/index.js` of the package:
|
|
26
76
|
|
|
27
77
|
```xml
|
|
78
|
+
<qti-response-declaration identifier="RESPONSE" cardinality="single" base-type="string"/>
|
|
79
|
+
…
|
|
28
80
|
<qti-portable-custom-interaction response-identifier="RESPONSE" module="pci" custom-interaction-type-identifier="blocks"
|
|
29
|
-
data-grid-divisions="
|
|
81
|
+
data-grid-divisions="4" data-brick-color-mode="single">
|
|
30
82
|
<qti-interaction-modules>
|
|
31
83
|
<qti-interaction-module id="pci" primary-path="../resources/pci/index"></qti-interaction-module>
|
|
32
84
|
</qti-interaction-modules>
|
|
@@ -34,21 +86,4 @@ building shown in the item. Made with [tspci](https://github.com/Citolab/tspci).
|
|
|
34
86
|
</qti-portable-custom-interaction>
|
|
35
87
|
```
|
|
36
88
|
|
|
37
|
-
with `<qti-response-declaration identifier="RESPONSE" cardinality="single" base-type="string">`.
|
|
38
|
-
|
|
39
|
-
## Settings
|
|
40
|
-
|
|
41
|
-
Each one is a `data-` attribute of the interaction, as text.
|
|
42
|
-
|
|
43
|
-
| attribute | editor | default | |
|
|
44
|
-
| ----------------------- | --------- | ---------------------------------------------------- | --------------------------------- |
|
|
45
|
-
| `data-grid-divisions` | integer | `2` (1–6) | grid size (cells per side) |
|
|
46
|
-
| `data-cube-pixel-size` | integer | `60` | brick size |
|
|
47
|
-
| `data-front-label` | text | `front` | label at the front |
|
|
48
|
-
| `data-brick-color-mode` | enum | `mixed` | `mixed` (multiple colours) or `single` |
|
|
49
|
-
| `data-brick-colors` | colorList | `#c91a09, #f2cd37, #0055bf, #237841, #fe8a18, #5aa5dc` | colours (one colour: the first) |
|
|
50
|
-
| `data-baseplate-color` | color | `#4b9f4a` | baseplate colour |
|
|
51
|
-
| `data-width` | integer | `400` | width (px) |
|
|
52
|
-
| `data-height` | integer | `400` | height (px) |
|
|
53
|
-
|
|
54
89
|
Source and the other examples: [Citolab/tspci-examples](https://github.com/Citolab/tspci-examples).
|
package/dist/authoring.json
CHANGED
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"descriptorVersion": "0",
|
|
3
3
|
"typeIdentifier": "blocks",
|
|
4
|
-
"version": "1.
|
|
4
|
+
"version": "1.2.0",
|
|
5
5
|
"label": "3d blocks",
|
|
6
6
|
"properties": {
|
|
7
7
|
"gridDivisions": {
|
|
8
8
|
"editor": "integer",
|
|
9
|
-
"default": "
|
|
9
|
+
"default": "5",
|
|
10
10
|
"min": 1,
|
|
11
11
|
"max": 6,
|
|
12
12
|
"label": {
|