Versions Compared

Old Version 1

changes.mady.by.user GE-DevDoc-Bot

Saved on

compared with

New Version Current

changes.mady.by.user GE-DevDoc-Bot

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • The Dynamic Image Point Viewer displays an image with interactive points overlaid.
  • It allows users to view and interact with specific locations on an image.
  • Points can change appearance based on data values.
  • It is suited for interactive maps, facility diagrams, or process visualizations.
  • The component supports dynamic data sources for images and points.

Example Point ViewerImage Added

Specs

Tokens

TokenDescription
displayNameDisplay name shown in the structure panel
imageUrlURL of the image displayed in the viewer
resizeImageStrategyStrategy for resizing image
fitToContainerScales the image to fit the container
useStaticSizeUses specified width and height values
fillWholeContentFills the entire container, may crop
useRealSizeDisplays the image at actual size
widthFixed width when using static size strategy
widthAutoAutomatically adjusts width to content
heightFixed height when using static size strategy
heightAutoAutomatically adjusts height to content
disableScrollbarControls visibility of scrollbars
paddingClassAdds spacing around the image viewer
thresholdConfigConditional styling rules for points
imageDataSourceIdData source ID for retrieving the image
getImageHttpRequestParametersMapHTTP parameters for image fetching
pointsDataSourceIdData source ID for retrieving points
getPointsHttpRequestParametersMapHTTP parameters for points fetching
positionXFieldNameField name for X coordinate
positionYFieldNameField name for Y coordinate
keyFieldNameField name for unique point identifier
displayFieldNameField name for tooltip display text
eventsConfigurable events the component can trigger
ON_IMAGE_POINT_CLICK (Events)Event when a point is clicked
ON_IMAGE_CLICK (Events)Event when the image is clicked
ON_IMAGE_POINT_DRAG_ENDED (Events)Event when a point drag ends
ON_IMAGE_POINT_VIEWER_CONTEXT_MENU_ACTION (Events)Event when a context menu action is selected
ON_GLOBAL_PARAMETERS_CHANGE (Events)Event when global parameters change
ON_INIT (Events)Event when the component is initialized
ON_DESTROY (Events)Event when the component is destroyed
contextMenuLabelText label for context menu actions
visibilityPolicySetIdPolicy set ID controlling visibility
displayConditionsRules for showing or hiding the component
dataTestIdIdentifier for automated testing
enableAsHotspotEnables guided tour hotspot
guidedTourHotSpotTitleTitle for guided tour hotspot
guidedTourHotSpotDescriptionDescription for guided tour hotspot

...

  • Renders a base image as the canvas and overlays viewer points; each viewer point combines spatial coordinates, a unique key, and a display label sourced from datasource fields.
  • Retrieves the base image and viewer points from dedicated datasources.

(Configured in General Properties)

  • displayName – Sets the display name of the component shown in the structure panel. For example, "Warehouse Floor Map" allows for easy identification of the component's purpose in the component structure, making it easier for developers to locate and work with this specific image viewer.

(Configured in Visual Properties)

  • imageUrl – Sets the URL of the image to be displayed in the viewer. For example, "https://example.com/floorplans/warehouse-a.jpg" provides the base image on which points will be overlaid. This property can also accept relative URLs to images stored within your application.
  • disableScrollbar – Controls whether scrollbars appear when the image is larger than its container. When set to true, scrollbars are hidden even if the image exceeds its container size, which can provide a cleaner appearance but may limit access to parts of the image.

(Configured in Visibility)

  • displayConditions – Defines conditions for displaying the component. This allows showing or hiding the image viewer based on complex rules involving form values, user roles, or application state. For example, the image viewer might only be shown when a specific building is selected.

Datasource

(Configured in Datasource)

...

  • positionXFieldName – Specifies the field name in the data source that contains the X coordinate for each point. For example, "locationX" tells the component which field in the data represents the horizontal position of each point on the image.
  • positionYFieldName – Specifies the field name in the data source that contains the Y coordinate for each point. For example, "locationY" tells the component which field in the data represents the vertical position of each point on the image.
  • keyFieldName – Specifies the field name that uniquely identifies each point. For example, "sensorId" helps the component track individual points and associate them with data records.
  • displayFieldName – Specifies the field name that contains the display text for each point's tooltip. For example, "sensorName" determines what text is shown when users hover over a point.

Point with dataImage Added

Styling

(Configured in General Properties)

...

in

...

(Configured in Visual Properties)

  • width – Sets the width of the image when using "useStaticSize" strategy. For example, "800px" sets a fixed width for the image viewer. This property accepts any valid CSS size value including pixels, percentages, or other units.
  • widthAuto – Controls whether the component width automatically adjusts to its content. When set to true, the component will take only as much width as needed; when false, it follows fixed width settings based on the container or specified values.
  • height – Sets the height of the image when using "useStaticSize" strategy. For example, "600px" sets a fixed height for the image viewer. This property accepts any valid CSS size value including pixels, percentages, or other units.
  • heightAuto – Controls whether the component height automatically adjusts to its content. When set to true, the component height is determined by its content; when false, it follows fixed height settings based on the container or specified values.
  • paddingClass – Configures spacing around the image viewer using CSS classes. For example, "p-3" adds medium padding on all sides of the component, improving its visual spacing within its container.
  • thresholdConfig – Configures conditional styling rules that change the color of points based on data values. For example, you can configure rules that render points as green when a status is "normal", yellow for "warning", and red for "critical", providing at-a-glance status information.

(Configured in Visibility)

  • displayConditions – Defines conditions for displaying the component. This allows showing or hiding the image viewer based on complex rules involving form values, user roles, or application state. For example, the image viewer might only be shown when a specific building is selected.

Actions & Variants

(Configured in Events)

...

  • visibilityPolicySetId – Determines the visibility of the component based on specified policy sets. For example, setting to "safetyMonitoringAccess" restricts the image viewer to users with specific safety monitoring permissions, allowing for role-based display of sensitive information.
  • Figma:
    • Image: https://www.figma.com/design/yck1tcUXgdQ5aYX6iUAwrO/GE---Astronaut-Design-System?node-id=11613-71930&t=ExcQFUXKvr1QdxTm-1
    • Data Points: https://www.figma.com/design/yck1tcUXgdQ5aYX6iUAwrO/GE---Astronaut-Design-System?node-id=11613-72440&t=ExcQFUXKvr1QdxTm-1
  • Live style guide: https://e1-dev.k8s.myapp.de/live-style-guide/other-components/image-point-viewer

Guidelines

Points Data Structure

...

  • positionXFieldName = "metadata.position.x"
  • positionYFieldName = "metadata.position.y"
  • keyFieldName = "id"
  • displayFieldName = "details.name"

Usage

  • Present an image with interactive points by binding the image and point sources and mapping fields: imageUrl or imageDataSourceId (+ getImageHttpRequestParametersMap), pointsDataSourceId (+ getPointsHttpRequestParametersMap), positionXFieldName, positionYFieldName, keyFieldName, displayFieldName.
  • Gate availability with displayConditions and visibilityPolicySetId.
  • Expose test and onboarding affordances via dataTestId, enableAsHotspot, guidedTourHotSpotTitle, guidedTourHotSpotDescription.

Sizing & Layout

  • Choose scaling with resizeImageStrategy: fitToContainer, fillWholeContent, useStaticSize (width, height, widthAuto, heightAuto), or useRealSize.
  • Control scroll affordances with disableScrollbar.
  • Add outer spacing with paddingClass.

Color & Contrast

  • Set point colors through thresholdConfig and ensure readability against the image; pair color with text from displayFieldName.

Tooltips

  • Keep hover text concise and recognizable by pointing displayFieldName to an appropriate label field.

Visibility & Authorization

  • Conditionally render via displayConditions.
  • Apply role-based visibility using visibilityPolicySetId.

Content & Localization

  • Localize guided tour copy with guidedTourHotSpotTitle, guidedTourHotSpotDescription; enable with enableAsHotspot.
  • Use displayName for authoring clarity in the structure panel.

Dos & Don’ts

DoDon’tArticle setting(s)
Bind both image and points from datasources so overlays match current data.Mix a hardcoded image with dynamic points from another source.imageDataSourceId, getImageHttpRequestParametersMap, pointsDataSourceId, getPointsHttpRequestParametersMap
Map coordinates and identity explicitly.Assume default field names.positionXFieldName, positionYFieldName, keyFieldName
Use exclusive rules for visual states.Overlap thresholds that cause flicker.thresholdConfig
Keep hover text short and clear.Cram long descriptions into hover.displayFieldName
Capture add-point coordinates on image click.Infer coordinates from unrelated UI.ON_IMAGE_CLICK
Persist edited positions when drag ends.Leave position changes uncommitted.ON_IMAGE_POINT_DRAG_ENDED
Offer explicit per-point actions.Overload single-click with many meanings.contextMenuLabel, ON_IMAGE_POINT_VIEWER_CONTEXT_MENU_ACTION
Choose a predictable sizing mode.Stretch/crop unpredictably.resizeImageStrategy, width, height, widthAuto, heightAuto
Hide the viewer until prerequisites are met.Show an empty/misleading canvas.displayConditions
Restrict sensitive imagery to authorized users.Expose restricted maps to all users.visibilityPolicySetId
Expose a stable automation hook.Use brittle DOM selectors.dataTestId
Localize onboarding copy.Ship a single-language tour.enableAsHotspot, guidedTourHotSpotTitle, guidedTourHotSpotDescription

Accessibility

...

  • Provide recognizable per-point text: displayFieldName. Keep the hover labels brief and specific.
  • Pair color with text to avoid color-only meaning: thresholdConfig + displayFieldName.
  • Reduce cognitive load by hiding non-applicable/restricted views: displayConditions, visibilityPolicySetId.
  • Localize tour copy when hotspots are enabled: enableAsHotspot, guidedTourHotSpotTitle, guidedTourHotSpotDescription.
  • Ensure high contrast for threshold-driven colors configured in thresholdConfig.
  • Prefer fitToContainer when dense markers require readability; use paddingClass to prevent edge crowding.
  • Guarantee unique point identity for stable updates: keyFieldName.