Set mesh opacity via frontend API (#9011)

### Steps to test:
- Open a DS or an annotation in webknossos and load any segments mesh
- Open the browser console and insert (with any color or opacity)
```
window.webknossos.apiReady(3).then((api) => {
api.data.setSegmentColor(<segmentId>, [0.3,0.5,0.7],<layerName>,0.5)
});
```

- check that the meshes opacity is changed accordingly.

### Issues:
- fixes #8974 

------
(Please delete unneeded items, merge only when none are left open)
- [x] Added changelog entry (create a `$PR_NUMBER.md` file in
`unreleased_changes` or use `./tools/create-changelog-entry.py`)
- [ ] Added migration guide entry if applicable (edit the same file as
for the changelog)
- [ ] Updated [documentation](../blob/master/docs) if applicable
- [ ] ~~Adapted [wk-libs python
client](https://github.com/scalableminds/webknossos-libs/tree/master/webknossos/webknossos/client)
if relevant API parts change~~ -> not needed, as the new function is
backwards-compatible
- [x] Removed dev-only changes like prints and application.conf edits
- [x] Considered [common edge
cases](../blob/master/.github/common_edge_cases.md)
- [ ] Needs datastore update after deployment

Author: knollengewaechs

frontend/javascripts/viewer/api/api_latest.ts

@@ -97,6 +97,7 @@ import {
   refreshMeshesAction,
   removeMeshAction,
   updateCurrentMeshFileAction,
+  updateMeshOpacityAction,
   updateMeshVisibilityAction,
 } from "viewer/model/actions/annotation_actions";
 import { setLayerTransformsAction } from "viewer/model/actions/dataset_actions";
@@ -2756,14 +2757,17 @@ class DataApi {
 
   /**
    * Set the RGB color of a segment (and its mesh) for a given segmentation layer. If layerName is not passed,
-   * the currently visible segmentation layer will be used.
+   * the currently visible segmentation layer will be used. If the mesh is loaded, optionally update its opacity.
    *
    * @example
-   * api.data.setSegmentColor(3, [0, 1, 1]);
+   * api.data.setSegmentColor(3, [0, 1, 1], "segmentation", 0.5);
    */
-  setSegmentColor(segmentId: number, rgbColor: Vector3, layerName?: string) {
+  setSegmentColor(segmentId: number, rgbColor: Vector3, layerName?: string, meshOpacity?: number) {
+    const state = Store.getState();
+    const additionalCoordinates = state.flycam.additionalCoordinates;
+    const additionalCoordKey = getAdditionalCoordinatesAsString(additionalCoordinates);
     const effectiveLayerName = getRequestedOrVisibleSegmentationLayerEnforced(
-      Store.getState(),
+      state,
       layerName,
     ).name;
 
@@ -2778,6 +2782,23 @@ class DataApi {
         true,
       ),
     );
+
+    if (meshOpacity != null) {
+      if (meshOpacity < 0 || meshOpacity > 1) {
+        throw new Error(`meshOpacity must be between 0 and 1, but got ${meshOpacity}`);
+      }
+      if (
+        state.localSegmentationData[effectiveLayerName]?.meshes?.[additionalCoordKey]?.[
+          segmentId
+        ] != null
+      ) {
+        Store.dispatch(updateMeshOpacityAction(effectiveLayerName, segmentId, meshOpacity));
+      } else {
+        throw new Error(
+          `Mesh for segment ${segmentId} was not found in State.localSegmentationData.`,
+        );
+      }
+    }
   }
 }
 /**

unreleased_changes/9011.md

@@ -0,0 +1,2 @@
+### Added
+- Added an optional `meshOpacity` parameter to `api.data.setSegmentColor`, allowing callers to set a segment's mesh opacity.