Skip to content

Commit

Permalink
Merge pull request #25 from klown/feat/palette-json-generator-webapp
Browse files Browse the repository at this point in the history 
Add a web application for generating palette JSON files
  • Loading branch information
@cindyli
cindyli authored Nov 6, 2024
2 parents 3558dd0 + 70e1a21 commit a94b8c4
Show file tree
Hide file tree
Showing 10 changed files with 28,528 additions and 1 deletion.
8 changes: 8 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,10 @@ how to run the software.
- [Ollama Chat Web-App](./apps/ollama/README.md): a chat application running on
`localhost` that provides access to multiple LLMs using the Ollama localhost
web service.
- [Palette Generator Web-App](./apps/palette-generator/README.md): an
application for generating and saving a palette using the Bliss gloss. By
providing a set of gloss words, BCI AV IDs, or svg builder strings, the Bliss
gloss is searched and a palette is generated based on matches found.
- [Ollama Chat Service Demo](./demos/Ollama%20Chat%20Service/README.md): a
simple web-app that runs on `localhost` for sending queries to an Ollama
chatbot service also running on `localhost`.
Expand All @@ -132,3 +136,7 @@ command" and "Build output directory" settings:

- Build command: `npm run build:client`
- Build output directory:: `/dist/client`

## Utility Scripts

- [Load a document into a vector databbase (`scripts/loadDocIntoVectorDb.js`)](./scripts/loadDocIntoVectorDb.js)
158 changes: 158 additions & 0 deletions apps/palette-generator/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,158 @@
# Palette Generator Web-App

## How to Launch

The palette generator is one of the web applications within this
project that run on localhost. It
is made available using the following command executed in the home directory:

```text
npm run serveAppsDemos
```

Once the development server is running, open this `localhost` url from within a
browser:
[`http://localhost:5173/apps/palette-generator/`](http://localhost:5173/apps/palette-generator/)

## How to Use

### Settings

The palette's settings are shown at the top of the page with the legend
"Settings". Within this block, use the "Palette name:" text field to enter a
name for the palette. The name can be any printable character including spaces.

The two number fields "Starting row" and "Starting column" allow you to specify
the top left corner of the palette. The default values are row 1, column 1, and
they refer to the position of the first cell in the first row of the palette.

The "Type of cell" select allows you to specify or modify the kind of cells that
make up the palette. Note that _all_ of the cells are set to this type; there
is no way to have a mixture of cell types. A future version of the application
will address this limitation.

### Search for matches

The next section, "Search for matches" is a text area where each line of text
describes one row of palette cells. Spaces are used for separate cells so the
text used to specify a cell cannot contain any spaces.

There are four types of input items allowed:

- a string that is a single word such as "heart" or "dog", or a string that
matches part or all of a gloss entry, e.g., "indicator_". As shown in this
last example, the string can include an underscore character (\_),
- a single number that is the BCI AV ID of a specific Bliss symbol,
- the text "BLANK" will result in an empty blank cell,
- an svg-builder string as required by the [bliss-svg-builder](https://github.com/hlridge/bliss-svg-builder)
that specifies component BCI AV IDs and shapes that the builder uses to create
the SVG graphic. More about the structure of this string is given below.

An svg-builder string is marked by "SVG:" at the beginning of the string and
":SVG" at the end. What lies between is a set of comma separated BCI AVI IDs,
and quoted strings that are parsed by the svg builder. No spaces are allowed
within an SVG string. Some examples of svg-builder strings:

```text
SVG:14905,"/",24883:SVG // "building" (14905) followed by "deletion" (24833) = "ruin"
SVG:13166,";",9011:SVG // "child" (13166) with plural indicator above (9011) = "children"
```

A user defined label for a cell can be specified for a word, ID, or an
svg-builder string. User defined labels cannot be added to `BLANK` cells. The
label to display is given by immediately appending "LABEL:_label\_text_" to the
word, number, or svg-builder string. The _label\_text_ will be used as the label
for the cell instead of the usual gloss for the symbol. Note that this is the
only way to specify a cell's label for svg-builder strings. The _label\_text_
cannot have any whitespace within it, since whitespace is used to indicate a new
cell in the palette. If white space is needed, use an underscore. Any
underscore characters in the _label\_text_ are replaced with a single space.
Some examples follow:

```text
clothLABEL:cross_hatches // cell label is "cross hatches"
23641LABEL:ruin // cell label is "ruin"; official gloss is "ruin,wreck,wreckage\_(building)\_(1)
SVG:13166,";",9011:SVGLABEL:children // cell label is "children"
```

### Generate Palette

Clicking the "Generate palette" button will trigger the app to use the
individual words and numbers to search the Bliss gloss for matches. In the case
of words, a match is defined as matching a single word within the gloss or
matching the entire gloss. Since the same word can appear in multiple glosses,
multiple matches are a possible result. Only the first match is used to
construct the cell, but all of the matches are reported in the lower part of the
page.

In the case of numbers, the gloss is searched for that unique BCI AV ID and that
single gloss entry is used to construct the cell. If the number is invalid, an
error is reported.

If the cell description string is an svg-builder string, the gloss is not
consulted. This has the consequence that the cell will not have a label since
the svg-builder does not know what the label is. Usually, however, if the user
knows the svg-builder string, they likely know the name of the symbol it
constructs, and can provide a label using the "LABEL:_label\_text_" technique.

For each match found, a cell is constructed and added to the appropriate row and
the entire palette is shown on screen. It can be inspected for errors.
Corrections can be made in the glosses area and a new palette generated by
clicking the "Generate palette" button again.

### Save Palette

Clicking the "Save palette" button will export a palette definition JSON file
and save it to disk where the browser saves file downloads, typically the
"Downloads" folder. The name of the file will be the palette's name with a
".json" extension. For example, if the palette name is "People", then the file
created is "People.json".

### Clear Palette

Clicking the "Clear palette" button removes the preview of the palette, and the
matches and error listings.

### Matches and Errors

#### Matches

The "Matches" section is a list of all of the matches that were found for each
item in the "Search for matches" input text area. Each item is listed
separately where the head of the listing is a copy of the input word. The
matches for each word are a list of the BCI AVI IDs and their glosses where a
word in the gloss matched. For example, if the input word was "cloth", two
gloss entries are reported. One is a symbol for cloth in the sense of fabric
(BCI AV ID 13365), and the other is a symbol for drying rack (BCI AV ID 26161):

```text
cloth
13365: cloth,fabric,material,textile,net
26161: drying_rack_(cloth)
```

If the Bliss symbol drawn in the preview palette is incorrect, the matches can
be consulted to see if there is a better symbol. If so, its BCI AV ID can be
input instead of the word initially used.

No matches are listed for BCI AV ID inputs, "BLANK" inputs, nor svg builder
strings. Valid BCI AV ID will match a Bliss gloss entry exactly and only errors
are reported if the ID is invalid. The gloss is not consulted for BLANK inputs
nor for svg builder strings.

#### Errors

The "Errors" section includes errors that arise from searching the gloss entries
or for invalid svg builder strings.

### Notes

The Bliss ID and gloss data source used by the generator is a large [JSON
file](https://raw.githubusercontent.com/cindyli/baby-bliss-bot/refs/heads/feat/bmw/data/bliss_symbol_explanations.json)
developed as part of a branch of the [baby-bliss-bot repository](https://github.com/inclusive-design/baby-bliss-bot/).
This branch has not been committed to the main repository as of this writing.

An alternative is a similar
[file](https://w3c.github.io/aac-registry/data/blissymbolics.json) under
development at the W3C. This is part of the [W3C Alternative and Augmented Communication (AAC) Symbol Registry](https://www.w3.org/TR/aac-registry/)
project; however, it also has draft status.
159 changes: 159 additions & 0 deletions apps/palette-generator/index.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,159 @@
<html>
<head>
<title>Palette Generator</title>
<style>
/*
* Needed to override palette button styles.
* TODO: modify palette's index.scss to add a class specifically for palette
* buttons, something like `button.palette { ... }`.`
*/
button.usual {
text-transform: none;
overflow: visible;
font-family: serif;
font-size: inherit;
margin: 0;
padding-top: 0.25em;
padding-left: 0.25em;
padding-right: 0.25em;
padding-bottom: 0.25em;
color: #000;
}
button.usual:disabled {
pointer-events: none;
}
button.usual:hover {
background-color: darkGray;
}
</style>
</head>
<body style="background-color: white; margin-left: 1em;">
<script type="module">
import "./palette-generator.ts";
</script>
<h1>Palette Generator</h1>
<div style="width:50%">
<fieldset>
<legend>Settings</legend>
<p>
<label for="paletteName">Palette name:</label><br>
<input type="text" id="paletteName" value="palette">
</p>
<p>
<label for="rowStart">Starting row (>=1):</label><br>
<input type="number" id="rowStart" min="1" max="100" value="1">
</p>
<p>
<label for="colStart">Starting column (>=1):</label><br>
<input type="number" id="colStart" min="1" max="100" value="1">
</p>
<p>
<label for="cellTypes">Type of cell:</label>
<select id="cellTypes"></select>
</fieldset>
</div>
<p>
<label for="glossInput">Search for matches:</label><br>
<textarea type="text" id="glossInput" rows="10" cols="175">
BLANK 25605 25605LABEL:ruin
indicator_(action) indicator_(action)LABEL:verb
SVG:13166,";",9011:SVG SVG:13166,";",9011:SVGLABEL:children
</textarea>
</p>
<details>
<summary>How to specify matches</summary>
<p>
List the items to search for in the "Search for matches:" text box above.
Each line corresponds to a row in the generated palette. Items are
separated by spaces and each item specifies a single cell. Each item is
one of:
</p>
<ul>
<li>
BLANK (all capitals), for a empty blank cell,
</li>
<li>
BCI AV ID, one of the official identifiers of a Bliss character or
Bliss word (Bliss symbol),
<ul>
<li>The cell's label is the gloss associated with the Bliss symbol.
</li>
</ul>
</li>
<li>
A single word or words separated by underscores. The glossary is
searched for words that match, or for a partial or exact match with the
gloss of an individual Bliss symbol. Mutitple matches are possible,
but only the first match is displayed in the preview.
<ul>
<li>The label is the given single word or underscore separated words.
</li>
</ul>
</li>
<li>
An svg-builder string, as defined by the <a href="https://github.com/hlridge/bliss-svg-builder">bliss-svg-builder</a>,
that defines the SVG image to use for the symbol,
<ul>
<li>The cell will have no label.</li>
</ul>
</li>
</ul>
<p>
Except for BLANK cells, you can optionally specify a label for each type of
item. Append
<code>LABEL:<span style="font-style: italic;">label_text</span></code> to
the end of the item. The <code style="font-style: italic;">label_text</code>
cannot have any spaces. If spaces are needed, use an underscore, "_" where
the underscores will be replaced with spaces. Some examples:
</p>
<ul>
<li><code>25605LABEL:ruin</code> will find the symbol whose BCI AV ID is
"25605". The cell's label is "ruin".
<ul>
<li>
If the <code>LABEL:ruin</code> is not appended, the label is the
gloss for 25605, namely, "ruin,wreck,wreckage_(building)_(1)".
</li>
</ul>
</li>
<li><code>indicator_(action)LABEL:verb</code> will find the
symbol whose gloss is "indicator_(action)". The cell's label is "verb".
<ul>
<li>
If the <code>LABEL:verb</code> is not appended, the label
is the given underscore separated words, i.e. "indicator_(verb)".
</li>
</ul>
</li>
<li><code>SVG:13166,";",9011:SVGLABEL:children</code> will generate the
an SVG image that combines the symbols that mean "child" and "plural".
The cell's label is "children".
<ul>
<li>
If no <code>LABEL:</code>is provided, the cell will have no
label.
</li>
</ul>
</li>
</ul>
<p>
When the page loads the first time, the above examples are shown in the
"Search for matches" text box. Press "Generate palette" button to
preview the palette and see the list of matehes below the preview.
</p>
</details>
<p>
<button id="generatePalette" class="usual">Generate palette</button>
<button id="savePalette" class="usual" disabled>Save palette</button><br>
Will save as the palette's name with a ".json" extension
<p id="saveMessage"></p>
</p>
<p><button id="clearPaletteDisplay" class="usual">Clear palette display</button></p>
<div id="paletteDisplay" style="border: 2px solid black;"></div>
<h2>Matches:</h2>
<div id="mainMatchesDisplay"></div>
<h2>Errors:</h2>
<p id="noErrors" style="display:none">No errors</p>
<ul id="errorList"></ul>
</body>
</html>
Loading

0 comments on commit a94b8c4

Please sign in to comment.