:tocdepth: 2

#########################
VizStreamerService gRPC 
#########################

************************
Overview
************************

The `VizStreamerService` is a *gRPC* service designed for streaming CAE visualization data, such as meshes, results, 
point clouds, textures, and associated settings. It provides methods to push various types of data to the service, 
manage groups, and handle frames and streams.

Below, you find documentation on all the Methods and Messages in the gRPC interface. For an introduction and more 
general documentation of how the *Visualization Streamer Service* works, please see the 
:doc:`Visualization Streamer Service <service>` topic.

You can also find similar methods described in more detail in the C++ Proxy documentation found in :doc:`proxy`. 

.. note

    In the subsequent chapter, any reference to the *Service* means the *Visualization Streamer Service*.


************************
RPC Methods
************************

IsAlive
=======

Checks if the server is active.

- **Request:** `EmptyMessage`
- **Response:** `IsAliveResponse`

PushIndexedPolygonMesh
=======================

Sends an indexed polygon mesh to the *Service*.

- **Request:** `PushIndexedPolygonMeshRequest`
- **Response:** `GenericPushResponse`

PushMeshScalar
==============

Sends a *Scalar* result that can be mapped on a *Mesh* to the *Service*.

- **Request:** `PushMeshScalarRequest`
- **Response:** `GenericPushResponse`

PushMeshVector
==============

Sends a *Vector* result that can be mapped on a *Mesh* to the *Service*.

- **Request:** `PushMeshVectorRequest`
- **Response:** `GenericPushResponse`

PushTexture
===========

Sends a 2D Texture image to the *Service*.

- **Request:** `PushTextureRequest`
- **Response:** `GenericPushResponse`

PushMeshTextureCoords
======================

Sends an array of 2D Texture coordinates (s,t) to the *Service*. They can be used to map a texture on a *Mesh*. One 
texture coordinate (s,t) per vertex in the *Mesh*.

- **Request:** `PushMeshTextureCoordsRequest`
- **Response:** `GenericPushResponse`

PushPointCloud
==============

Sends a point cloud to the *Service*. 

- **Request:** `PushPointCloudRequest`
- **Response:** `GenericPushResponse`

PushPointCloudVector
====================

Sends a *Vector* result to the *Service* that can be mapped on a *PointCloud*. 

- **Request:** `PushPointCloudVectorRequest`
- **Response:** `GenericPushResponse`

PushMeshSettings
================

Sends settings for a *Mesh* to the *Service*.

- **Request:** `PushMeshSettingsRequest`
- **Response:** `GenericPushResponse`

PushPointCloudSettings
======================

Sends settings for the *PointCloud* to the *Service*.

- **Request:** `PushPointCloudSettingsRequest`
- **Response:** `GenericPushResponse`

PushScalarSettings
==================

Sends setting for the *Scalar* mapping to the *Service*.

- **Request:** `PushScalarSettingsRequest`
- **Response:** `GenericPushResponse`

PushVectorSettings
==================

Sends settings for the *Vector* result to the *Service*.

- **Request:** `PushVectorSettingsRequest`
- **Response:** `GenericPushResponse`

AddMeshGroup
============

Sends the mesh instance configuration to the *Service*. 

- **Request:** `AddMeshGroupRequest`
- **Response:** `AddGroupResponse`

AddPointCloudGroup
==================

Sends the Point Cloud instance configuration to the *Service*. 

- **Request:** `AddPointCloudGroupRequest`
- **Response:** `AddGroupResponse`

CreateStream
============

Create a new *Stream* in the *Service*.

- **Request:** `CreateStreamRequest`
- **Response:** `EmptyMessage`

CreateAndPublishSingleFrame
===========================

Convenience function to show a single *Frame*. It deletes all Frames in the *Stream*, creates a new *Frame* and 
publishes this *Frame* to the *Stream*. 

Similar to ``CreateFrame``, this function is a server-side **barrier** that does not return until the frame is ready to 
stream from the server.

- **Request:** `CreateFrameRequest`
- **Response:** `CreateFrameResponse`

CreateFrame
===========

Create a new *Frame* in the given *Stream* on the *Service*. 

*CreateFrame* is a server-side **barrier** that does not return until the *Frame* is ready to stream from the server.

- **Request:** `CreateFrameRequest`
- **Response:** `CreateFrameResponse`

PublishFrames
=============

Publish one or more *Frames* to a specified *Stream*. This will make the *Frames* appear in any *Stream Model* 
subscribing to the *Stream*. 

- **Request:** `PublishFramesRequest`
- **Response:** `EmptyMessage`

DeleteFrames
============

Delete the specified *Frames* from the *Service*. This will allow the cleanup of data in the *Service* that is no 
longer referenced by any frames. To do this, use the ``DeleteUnreferencedData`` message.

- **Request:** `DeleteFramesRequest`
- **Response:** `EmptyMessage`

DeleteUnreferencedData
======================

Delete any data objects that are not referenced (directly or indirectly by the current list of *Frames* in any of the 
current *Streams*).

- **Request:** `DeleteUnreferencedData`
- **Response:** `EmptyMessage`

************************
Messages
************************

EmptyMessage
============

An empty message used when no data is required.

IsAliveResponse
===============

- **Fields:**

  - `server_message` (string): A message indicating the server status.

GenericPushResponse
===================

- **Fields:**

  - `resource_key` (string): The *ResourceKey* for the pushed resource.

PushIndexedPolygonMeshRequest
=============================

- **Fields:**

  - `vertex_arr` (repeated float): Array of vertex coordinates (x,y,z)
  - `index_arr` (repeated fixed32): Array of indices defining the polygons (indices into `vertex_arr`)
  - `fixed_vertices_per_poly` (uint32, optional): Number of vertices per polygon if fixed.
  - `vertices_per_poly_arr` (bytes, optional): Array specifying number of vertices per polygon.
  - `tag` (string, optional): An optional user-defined tag for the data object.

PushMeshScalarRequest
=====================

- **Fields:**

  - `bind_to_mesh_key` (string): ResourceKey for the *Mesh* to bind scalar values to.
  - `result_mapping` (ResultMapping): Mapping type for scalar values. Per vertex, per polygon, per polygon-vertex.
  - `value_arr` (repeated float): Array of scalar values (1D field).

PushMeshVectorRequest
=====================

- **Fields:**

  - `bind_to_mesh_key` (string): ResourceKey for the *Mesh* to bind vector values to.
  - `result_mapping` (ResultMapping): Mapping type for vector values. Per vertex, per polygon, per polygon-vertex.
  - `vector_arr` (repeated float): Array of vector values (3D field) (x,y,z).

PushTextureRequest
==================

- **Fields:**

  - `image_width` (uint32): Width of the texture image.
  - `image_height` (uint32): Height of the texture image.
  - `pixel_data_rgba` (bytes): Pixel data in RGBA format (byte colors).
  - `texture_options` (TextureOptions, optional): Additional texture options.
  - `tag` (string, optional): An optional user-defined tag for the data object.

PushMeshTextureCoordsRequest
============================

- **Fields:**

  - `bind_to_mesh_key` (string): ResourceKey for the *Mesh* to bind texture coordinates to.
  - `result_mapping` (ResultMapping): Mapping type for texture coordinates. Per vertex, per polygon, per polygon-vertex.
  - `tex_coord_2d_arr` (repeated float): Array of 2D texture coordinates (s,t).

PushPointCloudRequest
=====================

- **Fields:**

  - `vertex_arr` (repeated float): Array of point cloud vertices (x,y,z).
  - `tag` (string, optional): An optional user-defined tag for the data object.

PushPointCloudVectorRequest
===========================

- **Fields:**

  - `bind_to_point_cloud_key` (string): ResourceKey for the *PointCloud* to bind vectors to.
  - `vector_arr` (repeated float): Array of vector values (x,y,z).

PushMeshSettingsRequest
=======================

- **Fields:**

  - `draw_style` (DrawStyle): Drawing style for the mesh.
  - `color` (Color3f): Color of the mesh.
  - `opacity` (float, optional): Opacity level.
  - `flat_shading` (bool, optional): Whether to use flat shading or smooth shading.

PushPointCloudSettingsRequest
=============================

- **Fields:**

  - `color` (Color3f): Color of the point cloud.

PushScalarSettingsRequest
=========================

- **Fields:**

  - `min_range` (float): Minimum scalar value range for result mapping (color legend range).
  - `max_range` (float): Maximum scalar value range for result mapping (color legend range).

PushVectorSettingsRequest
=========================

- **Fields:**

  - `color` (Color3f): Color for vectors.
  - `scale_factor` (float, optional): Scale factor for vector visualization.

AddMeshGroupRequest
===================

- **Fields:**

  - `instance_arr` (repeated MeshInstance): Array of *ResourceKeys* for *Mesh* instances to add.

AddPointCloudGroupRequest
=========================

- **Fields:**

  - `instance_arr` (repeated PointCloudInstance): Array of *ResourceKeys* for *PointCloud* instances to add.

CreateStreamRequest
===================

- **Fields:**

  - `stream_name` (string): Name of the stream.
  - `description` (string): Description of the stream.
  - `suppress_error_if_stream_exists` (bool): Whether to suppress errors if the stream already exists.

CreateFrameRequest
==================

- **Fields:**

  - `stream_name` (string): Name of the stream to create a frame in.
  - `mesh_group_key_arr` (repeated string): Array of *ResourceKeys* for *MeshGroups* to include in the frame.
  - `point_cloud_group_key_arr` (repeated string): Array of *ResourceKeys* for *PointCloudGroups* to include in the frame.

CreateFrameResponse
===================

- **Fields:**

  - `resource_key` (string): The *ResourceKey* for the newly created *Frame*.

PublishFramesRequest
====================

- **Fields:**

  - `stream_name` (string): Name of the stream.
  - `frame_key_arr` (repeated string): Array (1..N) of *ResourceKey* for *Frames* to show in the client subscribing to this stream. 

DeleteFramesRequest


- **Fields:**

  - `stream_name` (string): Name of the stream.
  - `delete_all_frames` (bool): If true, all *Frames* will be deleted.
  - `delete_frame_key_arr` (repeated string): Array of *ResourceKey* for *Frames* to delete.
  - `keep_frame_key_arr` (repeated string): Array of *ResourceKey* for *Frames* to keep.


************************
Enums
************************

DrawStyle
=========

Specifies the drawing style for rendering meshes.

- `DS_UNSPECIFIED` (0): Unspecified style.
- `DS_SURFACE` (1): Solid surface rendering.
- `DS_SURFACE_MESH` (2): Surface (polygon) mesh rendering.
- `DS_SURFACE_OUTLINE_MESH` (3): Surface with (polygon) outline mesh.
- `DS_LINES` (4): Render as lines.
- `DS_POINTS` (5): Render as points.
- `DS_OUTLINE` (6): Outline rendering.
- `DS_HIDDEN_LINES_REMOVED` (7): Lines with hidden lines removed.

ResultMapping
=============

Specifies how values map to mesh elements.

- `RM_UNSPECIFIED` (0): Unspecified mapping.
- `RM_PER_VERTEX` (1): Values per vertex.
- `RM_PER_POLYGON` (2): Values per polygon.
- `RM_PER_POLYGON_VERTEX` (3): Values per polygon vertex.

TextureMinFilter
================

Specifies the texture minifying function.

- `TMIN_UNSPECIFIED` (0): Unspecified filter.
- `TMIN_NEAREST` (1): Nearest neighbor filtering.
- `TMIN_LINEAR` (2): Linear filtering.

TextureMagFilter
================

Specifies the texture magnification function.

- `TMAG_UNSPECIFIED` (0): Unspecified filter.
- `TMAG_NEAREST` (1): Nearest neighbor filtering.
- `TMAG_LINEAR` (2): Linear filtering.

TextureWrapMode
===============

Specifies the wrapping mode for textures.

- `TWRAP_UNSPECIFIED` (0): Unspecified mode.
- `TWRAP_REPEAT` (1): Repeat the texture.
- `TWRAP_CLAMP_TO_EDGE` (2): Clamp the texture to the edges.

************************
Data Types
************************

Color3f
=======

Represents an RGB color with float components (0..1).

- **Fields:**

  - `r` (float): Red component.
  - `g` (float): Green component.
  - `b` (float): Blue component.

TextureOptions
==============

Options for texture rendering.

- **Fields:**

  - `min_filter` (TextureMinFilter): Minification filter.
  - `mag_filter` (TextureMagFilter): Magnification filter.
  - `wrap_mode` (TextureWrapMode): Wrapping mode.
  - `environment_mapping` (bool): If true, environment mapping is used.

************************
Notes
************************

- **Tags:** Optional string identifiers for resources. They will not be used by the *Service*, but can be retrieved in 
  the client side *Stream Model*.
- **Resource Keys:** Unique identifiers returned upon pushing resources, used for future references to the resource 
  (data).
