User Guide
==========

The Street Smart plugin integrates CycloMedia Cyclorama imagery with QGIS. It opens an external Street Smart panorama viewer that stays in sync with the QGIS map canvas and can exchange overlays and measurements with your layers.

Quick start
-----------

#. Open **Settings Street Smart Plugin** and enter your CycloMedia credentials. Use username/password for the Atlas WFS. If your organization uses OAuth, check **Use OAuth Authentication** and provide your Client ID (you will sign in in the viewer). Keep the default URLs unless you were given custom endpoints.
#. Click **Add Atlas Recording WFS** to add the recordings layer. Zoom to 1:5000 or closer to see the layer named ``CycloMedia Recording``.
#. Click **Select Cyclorama point** and click a location on the map to launch the panorama viewer at that position.
#. (Optional) Toggle **Add Overlay layers to Panorama Viewer** to send visible vector layers within roughly 60 meters of the cone. Toggle **Start Measure** to capture measurements from the viewer into the active editable vector layer.

Toolbar
-------

The plugin menu and toolbar provide these commands:

- **Add Atlas Recording WFS** (always enabled): adds the Atlas recording WFS layer using the login credentials and filter described below.
- **Select Cyclorama point** (enabled after the WFS layer is present): click the map to open/update the panorama viewer and draw the viewing cone.
- **Add Overlay layers to Panorama Viewer** (enabled when the panorama viewer is open): pushes visible vector layers near the cone into the viewer.
- **Start Measure** (enabled when the panorama viewer is open): toggles measurement mode and writes results into the active editable vector layer.
- **Settings Street Smart Plugin**: configure authentication and endpoints.
- **Show help**: opens this help.

.. figure:: ../../../../doc/Toolbar.PNG
   :alt: toolbar image

   The buttons the plugin adds to the toolbar

.. figure:: ../../../../doc/Menu.PNG
   :alt: menu image

   The commands which are added by the Street Smart plugin

Add Atlas Recording WFS
-----------------------

- Adds the ``atlas:Recording`` WFS from the configured URL. By default the URL is ``https://atlasapi.cyclomedia.com/api/recording/wfs`` and the filter is ``expiredAt is null``. If you set a precision filter in Advanced Configuration (see below) it is appended to this filter.
- Uses the username and password from the Login tab for WFS authentication. OAuth is only used by the panorama viewer, so keep username/password filled when you need the WFS.
- The layer is named ``CycloMedia Recording``. Any existing layer with that name is removed first, and scale-based visibility is set to 1:5000 so you need to zoom in to view it.
- The layer is requested in ``EPSG:4326`` and added at the top of the layer tree.

Select Cyclorama point
----------------------

- Click the button, then click a point in the map to open the panorama viewer on that recording. The viewer starts in the current map CRS; if you change the project CRS, click a new point to refresh the viewer CRS.
- A cone is drawn on the map to show the panorama position and viewing direction. Walking through panoramas in the viewer keeps the same CRS until you select a new point in QGIS.

Add an overlay to the cyclorama window
--------------------------------------

- Works only while the viewer is open. Toggle the button to send overlays; toggling it off removes overlays from the viewer.
- All visible vector layers (except the recording layer) that are in scale range are sent as GeoJSON with their symbology. Features within roughly 60 meters around the cone are included and resent automatically when the cone moves.
- Make a layer visible in QGIS and toggle the overlay button again if you want to add it after the first send.

.. figure:: ../../../../doc/WithOverlay.PNG
   :alt: Viewer with overlays
   :figwidth: 50%

   The viewer with some vector layers as overlay.

The features shown are with 30 meters of the current Cyclorama. As long as the
overlay button is checked, QGIS will send the features within the query
distance around the cone to the viewer. The user can set the visiblity of the
layers in the viewer.

If a layer that was not visible in QGIS should still be sent to the viewer, the
user must first make it visible. By toggling the overlay button, the additional
layer is sent to the viewer.

Create a measurement
--------------------

- Works only while the viewer is open. Select an editable vector layer before toggling **Start Measure**; the plugin will start editing the layer if needed.
- The measurement tool in the viewer matches the active layer geometry: point, line, or polygon. The active measurement is written to the active layer; starting a new measurement in the viewer creates a new feature.
- Turning the toggle off stops measurement mode and disconnects from further updates. Closing the viewer also stops measurement.

.. figure:: ../../../../doc/StartMeasurementLocation.PNG
   :alt: Start a point measurement
   :figwidth: 50%

   The view when a point layer is selected in measurement mode.

.. figure:: ../../../../doc/StartMeasurementDistance.PNG
   :alt: Start a polyline measurement
   :figwidth: 50%

   The view when a polyline layer is selected in measurement mode.

.. figure:: ../../../../doc/StartMeasurementSurface.PNG
   :alt: Start a surface measurement
   :figwidth: 50%

   The view when a polygon layer is selected in measurement mode.

Settings
--------

- **Login**: choose authentication. For basic authentication, enter username and password. For OAuth, check **Use OAuth Authentication** and provide a **Client ID**; you will sign in when the viewer opens. The API key can remain at its default unless your organization provides a different key.
- **Configuration**: optional overrides for the configuration URL, StreetSmart API URL (default v25.7), and the Atlas Recording WFS URL. Use the **Use default** checkbox to revert to the built-in endpoints.
- **Advanced Configuration**: an optional *Filter on location* section to apply a WFS filter. Leaving **Use default** checked keeps the filter ``expiredAt is null``. Clearing it lets you set latitude/longitude/height precision thresholds; the filter applied looks like ``expiredAt is null AND latitudePrecision > X OR longitudePrecision > Y`` using your values.
- **About** and **Agreement**: version information and license.

Tips
----

- The overlay and measurement buttons stay disabled until the panorama viewer is running.
- If no recordings appear, confirm your username/password, the Atlas WFS URL, and zoom to 1:5000 or closer.
- On first use the plugin may install supporting Python packages (cefpython3, geojson, shapely). Restart QGIS if prompted.
