Floors Map Widget

This widget allow you to create an interactive floors map from an SVG image.

build release

ru

Logo

Table of Contents

About the Project

This widget allows you to create an interactive floor map based on an SVG image.

Features

  • Generation of an interactive map based on an SVG image.
  • Creating and visualizing routes between different points.
  • Configuring interactions when clicking on a block.
  • Tiled SVG rendering for smoother work with large maps.
  • Optional tile debug overlay for inspecting visible tile ranges and cache behavior during development.

Supported Object Classes

  • shop
  • parkingspace
  • atmmachine
  • toilet
  • stairs

Toilet SubTypes

  • male
  • female
  • mother_and_child

Stairs SubTypes

  • simple
  • fire_escape
  • escalator
  • elevator

How to Use

Working with the library is divided into several stages.

Stage 1 - Adding Route Points

Using Inkscape or any other SVG editor, create a floor map or use an existing one. Now, you need to prepare this map to work with FloorMapWidget. You need to set route points and entrance points to room objects. You can use the ready-made Inkscape extension floors_map_extension or do it manually.

Inkscape Extension

The floors_map_extension Inkscape extension helps prepare SVG maps for this widget: it can connect selected point shapes, assign compatible point/building IDs, create entrance points, link building objects to their entrances, and clean up no-longer-linked points. Use it when you want the SVG to follow the ID patterns expected by FloorSvgParser without editing every object id by hand.

MapPlaginExample1 MapPlaginExample2

Manual Implementation

You can use either a circle shape or a custom shape using a path. Point binding occurs using the id attribute. For example, in this example, we created a point in two ways and connected it to three neighboring points.

point-43=44-39-45
│     │  └‒‒└‒‒└‒‒‒‒‒ unique IDs of connected neighbors
│     └‒‒‒‒‒ unique ID of the object
└‒‒‒‒‒ class of the object - point

<circle id="point-43=44-39-45" cx="4.5" cy="4.5" r="4.5" fill="black"/>

<path id="point-43=44-39-45" d="M4.2 8.39999C6.52 8.39999 8.39999 6.52 8.39999 4.2C8.39999 1.88 6.52 0 4.2 0C1.88 0 0 1.88 0 4.2C0 6.52 1.88 8.39999 4.2 8.39999Z" fill="black"/>

Stage 2 - Assigning Correct IDs to Room Objects

You can see the supported objects here. The rules for creating IDs are the same as for Point.

shop-1=2
│    │ └‒‒‒‒‒ unique ID of the connected entrance point (there can be only one)
│    └‒‒‒‒‒ unique ID of the object
└‒‒‒‒‒ class of the object

stairs-elevator-1=2
│      │        │ └‒‒‒‒‒ unique ID of the connected entrance point (there can be only one)
│      │        └‒‒‒‒‒ unique ID of the object
│      └‒‒‒‒‒ subtype of the object (required for stairs and toilet)
└‒‒‒‒‒ class of the object

Ready Example

<path id="shop-3=5" d="M477.648 206.928H428.712V323.772H565.44V315H569.448V235.404H481.044H477.648V231.996V206.928Z" fill="#EEF9FE" />

Stage 3 - Integrating the Library into Your Project

Add the library to your project and embed the ready widget containing the necessary parameters.

FloorMapWidget(
  // String from SVG Map
  _svgContent,
  // Floor widgets
  _listWidgets,
  // Optional: parsed route points. If omitted, FloorMapWidget parses them.
  listPoints: _listPoints,
  // Use to build a route
  startIdPoint: _startPointItem?.idPoint,
  endIdPoint: _endPointItem?.idPoint,
  // Use to remove point markers from SVG string rendering
  unvisiblePoints: true,
),

By default, the widget renders the SVG through the tiled renderer. This keeps the map layer independent from interactive item overlays and reduces repeated raster work while panning and zooming.

For development, enable the tile debug overlay:

FloorMapWidget(
  _svgContent,
  _listWidgets,
  debugTiles: true,
)

The debug panel is pinned to the top-right corner of the app overlay and can be collapsed by tapping it. It shows the currently displayed/visible tile count, visible tile range, effective/requested raster scale, cached and pending tiles, cache hits/misses, generated tiles, and pruned tiles.

For advanced zoom-quality control, pass your own TransformationController and ValueNotifier<SvgMapRenderProperties>:

final transformationController = TransformationController();
final renderPropertiesNotifier = ValueNotifier(
  SvgMapRenderProperties(
    svgData: svgContent,
    svgSource: SvgSource.string,
    mapSize: null,
    renderingStrategy: RenderStrategy.picture,
  ),
);

FloorMapWidget(
  svgContent,
  itemWidgets,
  listPoints: points,
  transformationController: transformationController,
  renderPropertiesNotifier: renderPropertiesNotifier,
)

FloorMapWidget parameters

Parameter Type Required Description
svgContent String Yes Raw SVG markup used by the default string source.
listItemsWidgets List<FloorItemWidget> Yes Interactive item overlays rendered above the map layer.
listPoints List<FloorPoint>? No Parsed route points. If omitted, they are parsed from svgContent.
renderPropertiesNotifier ValueNotifier<SvgMapRenderProperties>? No External map render state for advanced SVG source, quality, and loading control.
transformationController TransformationController? No Shared controller for the parent InteractiveViewer and tiled renderer.
unvisiblePoints bool No Removes point markers from string SVG rendering. Defaults to false.
debugTiles bool No Enables the collapsible tile debug overlay. Defaults to false.
startIdPoint int? No Start route point id.
endIdPoint int? No End route point id.

SvgMapRenderProperties parameters

Parameter Type Default Description
svgData Object Required Raw SVG string, SVG asset path, or compiled vector graphic asset path.
svgSource SvgSource Required Source kind: SvgSource.string, SvgSource.asset, or SvgSource.compiled.
mapSize Size? Required Render size. FloorMapWidget keeps it in sync with its layout constraints.
loadingPlaceholder Widget? null Widget shown while the SVG picture is loading.
renderquality double 5 Requested tile raster quality. The tiled renderer caps the effective quality to the current viewport scale.
renderingStrategy RenderStrategy? RenderStrategy.raster flutter_svg rendering strategy used by the SVG loader.

To add interactive objects to the map, initialize them with FloorItemWidget and pass the resulting list to FloorMapWidget.

FloorItemWidget(
    // FloorItem
    item: element,
    // Function (FloorItem)
    onTap: _handleFloorItemTap,
    // An example of how to change the color of an
    // interaction animation
    selectedColor: Colors.orange[200]!.withOpacity(0.5),
    // An example of how to turn on an object's blinking
    // Thanks to this, you can highlight some objects on the map.
    // For example toilets or ATM
    isActiveBlinking: false,
),

FloorItemWidget parameters

Parameter Type Default Description
item FloorItem Required Parsed interactive object from the SVG.
onTap Future<void> Function(FloorItem)? null Called when the object is tapped.
durationTapAnimation Duration 50ms Tap highlight animation duration.
durationBlink Duration 1s Blinking highlight animation duration.
isActiveBlinking bool false Enables repeated blinking highlight.
selectedColor Color? null Highlight color. Falls back to a default translucent color.
parentSize Size? null Parent map size. Usually set by FloorMapWidget automatically.

You can get the objects using FloorSvgParser.

final parser = FloorSvgParser(svgContent: svgContent);
// You can get anchor points from the map
final listPoints = parser.getPoints();
// You can get all objects supported by the library
final listItems = parser.getItems();

For more information, visit the Example with prepared code and map example.

Example

How to Contribute

To get started, read CONTRIBUTING.md to learn about the guidelines within this project.

Changelog

Refer to the Changelog to get all release notes.

Maintainers

LOGION

Valerij Shishov | Arthur Lokhov | Brdn Velazquez

This library is open for issues and pull requests. If you have ideas for improvements or bugs, the repository is open to contributions!

Libraries

floors_map_widget