diff --git a/README.md b/README.md index 5b80ae5..c4410a4 100644 --- a/README.md +++ b/README.md @@ -64,61 +64,6 @@ Then in a new terminal run the tests: npm run test ``` - -## Purpose - -## Functionalities -### Moving the viewpoint -Left click and hold anywhere on the screen, while moving the mouse or use a second finger on the touchpad to dynamically move the viewpoint. By doing this you can tilt and rotate the viewpoint. - -### Zoom -To zoom in and out the user can either: -1. Utilize the scroll wheel on a mouse. -2. Drag two fingers on the touchpad towards each other or away from each other. - -### Move -To move within the application, double click on a point and you will automatically be moved to that point. -If you want to move across larger distances, for example look at a point from a different point cloud, it is recommended to zoom out first and then choose a point closer to where you want to be positioned. -###Coordinates -In the bottom right corner there is a black box that lists coordinates. These coordinates correspond to the target point, which is continuously updated to be the most resent point the user has clicked on. Latitude and longitude are measured in degrees, while elevation is measured in metres from the surface level. - -### Menu Bar -The icon of three vertical lines stacked in the top left corner show and collapses the sidebar where most of the functionalities are located. - -### Minimap -The map icon below the menu bar icon in the top left corner, will show and collapse a minimap. -In the minimap you can zoom using the mouse, touchpad or the icons in the top left corner. -You can move around by clicking and moving the mouse around simultaneously. - -### Points -Points can be saved by clicking on the icon in the image below in the Measurements tab, then clicking on the point in the point cloud. -A point will show up under list of measurements and points in a list. -XYZ values ask Klein -The x y z coordinates at the top are Earth Cantered Earth Fixed(ECEF) coordinates, EPSG 4978. -The data for each point in the table below is: latitude and longitude in degrees, elevation measured from the sea level, point source, accepted status, Total Vertical Uncertainty(TVU) and Total Horizontal Uncertainty(THU). -To delete a point, click on the red x to the right of the point in the List of measurements. -There is added toggle functionality below the list of points to hide and show all point labels on the point cloud, see image below. - -### Annotations -Annotations can be created under the Saved Locations section in the side bar. Click the Add a location button, then click on a point in the point cloud. As you hover over points in the point cloud, there should be an annotation label above the cursor to confirm that you can choose a point now. -The annotation will be added to a list below the add a location button upon creation. -There are three icons on the annotation. The pen icon allows you to rename the annotation, the arrow icon allows you to lerp to the annotation from anywhere on the map and the red x icon will delete the annotation. -When pressing the annotation text on the saved annotation, you can add a description by clicking the pen icon to the right of Annotation Description. The point coordinates and the camera coordinates will be displayed below the annotation description. -There is added toggle functionality below the list of annotations to hide and show all annotation labels on the point cloud, see image below. - -### Compass -Under Tools in the menu bar, there is a compass icon that will display a compass in the top right corner when you press it. Collapse it by clicking once more on the compass icon in the menu bar. - -### Colour scale -There are nine different gradient schemes to choose from under the Elevation Control tab. You change the colour scale for all the point clouds by clicking them. - -### Elevation Control -Elevation control applies gradient based on the elevation of the data points, and can be adjusted on the elevation range slider under the elevation control tab. - -### Height Profile -Under Measurements in the menu bar there is functionality to create a height profile. Click the 2D height profile icon showed in the image below. Now you can click on the desired points in the point cloud. The order you click on the points matter, start with clicking on the first point you want to show up in the diagram, move to the second point and so on. When you have clicked on all the points you want to include, you can right click anywhere in the point cloud to exit this add point mode. Go back to the menu bar, the points will be saved under List of Measurements for the profile you made. Display the height profile by clicking the show 2d profile button at the bottom of the measurements section. If nothing shows up, make sure that your desired profile is selected first under list of measurements and profile, by clicking on it. When you chow the height profile, you can hover over the 2D profile and see a marker in the point cloud move, visualizing where the points are taken from. Collapse the height profile by clicking at the black x in the top right corner of the pop-up window. - -### Filtering for accepted points -Under the Accepted Filter tab in the menu bar there is a button for Activate accepted filter. When pressing this button, all the points in the point clouds will be displayed as either black: for not accepted or white: for accepted. The acceptance data of a point is an attribute that shows whether the point is accepted as part of the seabed. -To display the point cloud with colour again, go to the elevation control tab and press the activate elevation control button. +### User Guide +For a complete User Guide to fundamentals and all functionality click [here](src/UserGuide/Userguide.md). diff --git a/src/UserGuide/Userguide.md b/src/UserGuide/Userguide.md new file mode 100644 index 0000000..70e8d72 --- /dev/null +++ b/src/UserGuide/Userguide.md @@ -0,0 +1,359 @@ +# User Guide +This is a userguide for all functionality found in Molloy Explorer. For general information and SetUp, see [README](../../README.md) +## Table of Contents +- [Fundamentals](#fundamentals) + - [Moving the viewpoint](#moving-the-viewpoint) + - [Zoom](#zoom) + - [Move](#move) +- [Menu Bar](#functionalities) + - [Elevation Control](#elevation-control) + - [Accepted Filter](#accepted-filter) + - [Measurements](#measurements) + - [Saved Locations](#saved-locations) + - [Appearance](#appearance) + - [Tools](#tools) + - [Scene](#scene) + - [About](#about) +- [Minimap](#minimap) +- [Coordinates](#coordinates) + + +## Fundamentals + +### Moving the Viewpoint +Left click and hold anywhere on the screen, while moving the mouse or use a second finger on the touchpad to dynamically move the viewpoint. By doing this you can tilt and rotate the viewpoint. + +### Zoom +To zoom in and out the user can either: +Utilize the scroll wheel on a mouse. +Drag two fingers on the touchpad towards each other or away from each other. + +### Move +To move within the application, double click on a point you wish to explore further and you will automatically be moved closer to that point. +If you want to move across larger distances, for example look at a point from a different point cloud, it is recommended to zoom out first and then double click on a point closer to where you want to be positioned. + +## Menu Bar + +In the top left corner there are two icons: +The top icon opens the menu bar and the bottom icon shows and collapses the minimap. Most of the functionalities are located in the menu bar. + + icons + + +There are eight tabs in the menu bar that can be opened and collapsed by clicking on them. + +tabs + +### Elevation Control +--- +Elevation control applies gradients based on the elevation of the data points. +By default elevation control is active. The “Activate elevation control” button will be visible and can be pressed after looking at the Accepted Filter(link to section below?) to reset the view back to default. See image below. +Use the slider to set the range by clicking and dragging the squares on either end of the scale. +Gradient is set to Clamp by default, but can be changed to “Repeat” or “Mirrored Repeat” by clicking on them. +There are nine different gradient schemes to choose from. These are also selected by clicking on them. + +ElevationControl + +ElevationControl + +### Accepted Filter +--- +The accepted filter contains one button to change the view to show which datapoints are accepted as part of the seabed, when the elevation control is active. When the “Activate accepted filter” button is pressed, information regarding the coloring of the datapoints is displayed. This data regarding if a point is accepted or not is an attribute to each datapoint and can not be changed. + +AcceptedFilter + +AcceptedFilter + +### Measurements +--- +The Measurements tab allows you to measure angles, distances, heights, areas, volumes, and other properties directly within the point cloud. All tools are located in the Measurements tab in the menu bar. You can perform multiple measurements simultaneously, and all results are tracked in the "List of Measurements" section. + +Measurements + +#### Measure Angle +To measure angles between points: +1. Click on the "Measure Angle" icon or text. +2. Click three points in the point cloud. A red triangle will appear connecting the points, and the corresponding angle will be displayed. +To adjust a point in the triangle, click on the point you want to move, then click a new point in the point cloud. +There is no limit to the number of triangles you can display. +Measurement details appear in the "List of Measurements" below the menu bar. The default name is "Distance#1"; make sure it is selected when reviewing the data. + +#### Inspect Point +To inspect a point in the point cloud: +1. Click the "Inspect Point" icon. +2. Click on the point you want to examine. +The coordinates and other available attributes of that point will be displayed in the corresponding panel. + +#### Measure Distance +To measure the distance between two points: +1. Click the "Measure Distance" icon. +2. Click the first point, then the second point in the point cloud. +The distance between the points will be displayed, and a connecting line will appear. +To adjust points, click the point and select a new location. + +#### Measure Height +To measure vertical height differences: +1. Click the "Measure Height" icon. +2. Click the lower point first, then the higher point. +The vertical distance will be displayed. + +#### Circle +To measure a circle: +1. Click the "Circle" icon. +2. Click the center point, then a point on the circumference. +The radius and circumference will be displayed. + +#### Azimuth +To measure azimuth (direction relative to north): +1. Click the "Azimuth" icon. +2. Click the starting point, then the ending point. +Azimuth measures the directional angle in degrees between two points relative to true north. + +#### Area +To measure a polygonal area: +1. Click the "Area" icon. +2. Click points to form the vertices of the polygon. +3. Double-click the last point to complete the polygon. +The calculated area will be displayed. + +#### Volume +To measure a 3D volume: +1. Click the "Volume" icon. +2. Select points to define the base polygon of the volume. +3. Click an additional point to define the top plane (height). +The volume enclosed by the selected points will be calculated. + +#### Sphere Volume +To measure a sphere’s volume: +1. Click the "Sphere Volume" icon. +2. Click the center point of the sphere, then a point on the surface to define the radius. +The sphere volume will be displayed. + +#### 2D Height Profile +To generate a 2D height profile along a line: +1. Click the "2D Height Profile" icon. +2. Click the starting point of the profile line, then click the ending point. +The profile line will appear, and a 2D plot of height along the line will be displayed. +You can hover over or click points on the profile to see specific elevation values. +Multiple profile lines can be drawn for comparison. +To adjust the profile line, select a point and move it to a new location. + +#### Remove All +Click the "Remove All" icon to clear all measurements currently displayed in the scene. This will remove all lines, polygons, volume measurements, height profiles, and labels at once. + +#### Deleting Measurements +To delete individual measurements: +1. Select the measurement in the "List of Measurements". +2. Click the red "x" icon next to the measurement. +This applies to all measurement types including angles, distances, heights, areas, volumes, spheres, circles, azimuths, and 2D height profiles. + +#### Show/Hide Labels +To show or hide labels for measurements: +1. Click the "Show Labels" button to display labels for all measurements currently in the scene. +2. Click the "Hide Labels" button to hide all measurement labels without deleting the measurements themselves. +This applies to all measurement types, including angles, distances, heights, areas, volumes, spheres, circles, azimuths, and 2D height profiles. + +#### List of Measurements +All measurements are tracked in the "List of Measurements" panel at the bottom of the menu bar. Each measurement can be selected to view detailed information or deleted individually. This list provides an easy way to manage multiple measurements in a large point cloud. + +### Saved Locations +--- +The Saved Locations tab allows you to quickly navigate to specific points or viewpoints that you have saved within the scene. Annotations can also be created here to mark points of interest. By default, annotation labels are visible in the point cloud and on the map, making it easy to locate important areas. + +SavedLocations + +SavedLocations + +#### Show/Hide Annotations +Below the list of annotations, there are toggle buttons to show or hide all annotation labels in the point cloud. Use this to declutter the view or focus on specific points as needed. + +#### Creating an Annotation +To create an annotation: +1. Click the "Add a Location" button in the Saved Locations section. +2. Click on a point in the point cloud. +As you hover over points, an annotation label will appear above the cursor to indicate that a point can be selected. +The annotation will be added to a list right below the "Add a Location" button upon creation. + +#### Managing Annotations +Each annotation in the list has three icons: +- **Pen Icon** – Rename the annotation or edit its description. +- **Arrow Icon** – Move the camera to the annotation from anywhere in the scene. +- **Red X Icon** – Delete the annotation. + +To add a description to an annotation: +1. Click the annotation text in the Saved Locations list. +2. Click the pen icon next to "Annotation Description". +The point coordinates and the current camera coordinates will be displayed below the description field. + +### Appearance +--- +The Appearance tab allows you to adjust the visual rendering and display settings of the point cloud and scene to optimize clarity, performance, and visual preference. + +Appearance + +#### Point Budget +The Point Budget controls the maximum number of points rendered at any time. +- Adjustable using a slider ranging from **100,000 to 10,000,000 points**. +- Higher values provide more detail but may impact performance, while lower values improve performance at the cost of detail. + +#### Field of View +The Field of View (FOV) controls the camera’s viewing angle. +- Adjustable using a slider ranging from **20° to 100°**. +- A wider FOV shows more of the scene but may distort perspective, while a narrower FOV provides a more focused view. + +#### Eye-Dome Lighting (EDL) +Eye-Dome Lighting enhances depth perception by shading points based on their relative distance. +- **Enable Checkbox** – Turn EDL on or off. +- **Radius Slider** – Adjusts the size of the area used to calculate shading. +- **Strength Slider** – Controls the intensity of the depth effect. +- **Opacity Slider** – Adjusts the transparency of the shading effect. + +#### Background +The Background setting controls the scene’s visual backdrop. Options include: +- **Skybox** – A textured 3D background simulating a sky. +- **Gradient** – Smooth transition between two colors. +- **Black** – Solid black background. +- **White** – Solid white background. +- **Globe** – Displays the Earth or a globe representation, this is the default. + +#### Other Settings +- **Splat Quality** – Adjusts the rendering quality of point splats: + - **Standard** – Default quality, optimized for performance. + - **High Quality** – Improved visual detail, may impact performance. +- **Min Node Size** – Controls the smallest size of nodes rendered in the point cloud. +- **Box** – Toggle the visibility of bounding boxes around point clouds or objects. +- **Lock View** – Keeps the bounding boxes or other visual guides in a fixed position. + +### Tools +--- +The Tools section is located in the menu bar and contains functionalities for clipping, navigation, camera control, and speed adjustment. Clicking on a tool will open the corresponding options. + +Tools + +#### Clipping + +Clipping allows you to focus on specific regions of the point cloud or dataset by hiding or highlighting data based on user-defined areas. + +- **Volume Clip** + Lets you define a 3D box or other volume to clip the data inside or outside of it. This is useful when you want to focus on a particular region of the seabed or point cloud. + +- **Polygon Clip** + Allows you to draw a polygon on the screen and clip data based on the shape of that polygon. Only data inside or outside the polygon will be affected depending on your settings. + +- **Draw a Selection Box** + Enables you to quickly create a rectangular selection in the scene. This box can then be used as a clipping volume to isolate a section of the dataset. + +- **Remove All Clipping Volumes** + Resets all clipping operations and displays the entire dataset again. Use this when you want to start over or remove all applied selections. + +#### Clip Task + +The Clip Task determines what happens to the points in the clipping area: + +- **None**: No changes are applied to the points within the clip volume. +- **Highlight**: Points within the clipping area are highlighted to make them easier to see. +- **Inside**: Only points inside the clipping area remain visible; all others are hidden. +- **Outside**: Only points outside the clipping area remain visible; all points inside are hidden. + +#### Clip Method + +When multiple clipping volumes are active, the Clip Method determines how they are combined: + +- **Inside Any**: Points inside any of the clipping volumes will be affected. This creates a union of all clipping areas. +- **Inside All**: Points must be inside all defined clipping volumes to be affected. This creates an intersection of all volumes. + +#### Navigation + +Navigation tools allow you to move around the dataset and view it from different angles or perspectives. + +- **Earth Control** + Moves the camera around the globe, allowing rotation, panning, and tilting. Useful for general exploration of the point cloud relative to the Earth’s surface. + +- **Fly Control** + Simulates a flying camera, allowing smooth free movement in any direction. Useful for inspecting large areas of the seabed. + +- **Helicopter Control** + Similar to Fly Control, but movement mimics the behaviour of a helicopter, including tilt and banking effects. + +- **Orbit Control** + Lets the camera orbit around a selected point, object, or region. Ideal for inspecting objects from multiple angles without changing the target point. + +- **Full Extent** + Resets the view to show the entire dataset or point cloud. This is useful if you have zoomed in too far or moved to a specific area and want to see the whole scene. + +- **Navigation Cube** + A visual cube in the scene that allows you to quickly change views by clicking on its faces, edges, or corners. It can switch between standard perspectives like top, side, or front views. + +- **Compass** + Displays a compass in the top right corner of the screen. This shows the current orientation and allows you to reset the view to north-up. + +- **Camera Animation** + Lets you create or play smooth camera movements, such as flying along a path or rotating around a point. + +- **Left View / Right View / Front View / Back View / Top View / Bottom View** + Predefined fixed perspectives that allow you to quickly switch to standard orthogonal views of your dataset. + +#### Camera Projection + +Camera projection defines how depth and distance are perceived in the 3D view. + +- **Perspective** + Standard 3D view where objects appear smaller as they get farther away. This view simulates how humans naturally perceive depth. + +- **Orthographic** + Objects maintain the same size regardless of distance. This is useful for technical inspections, measurements, or plan views where perspective distortion is not desired. + +#### Speed + +The Speed control adjusts how fast the camera or navigation responds to user inputs. + +- Increasing speed makes zooming, panning, and flying faster, which is useful for exploring large datasets quickly. +- Decreasing speed allows for precise adjustments when inspecting small details or measuring specific points. +- The speed will be adjusted automatically when you zoom in and out, providing a more intuitive navigation experience. + +This section ensures that all users can efficiently navigate and manipulate the point cloud data, while providing control over the view, clipping, and camera behaviour. + + +### Scene +--- +The Scene tab allows you to manage and organize all the elements currently loaded in the application. It provides tools to view, modify, and export components such as point clouds, measurements, annotations, and other objects, giving you complete control over the content of your 3D environment. + +Scene + +#### Export +The Export feature allows you to save elements from the scene into different file formats for external use: +1. **JSON** – Exports the scene configuration and metadata for use in other applications or for project backup. +2. **DXF** – Exports measurements and geometry into a CAD-compatible format. +3. **Potree** – Exports the point cloud and scene data into a Potree-compatible format for web-based visualization. + +#### Objects +The Objects section lists all items currently present in the scene, grouped into categories: +- **Point Clouds** – Displays all loaded point clouds in the scene. You can toggle visibility, inspect properties, or remove them. +- **Measurements** – Shows all measurements currently in the scene, including angles, distances, heights, areas, volumes, and 2D height profiles. +- **Annotations** – Displays any annotations added to the scene, allowing for review or modification. +- **Other** – Contains additional scene elements: + - **Camera** – Tracks the position and orientation of the current viewpoint. +- **Vectors** – Displays any vector elements present in the scene. +- **Images** – Shows any images linked to points or objects in the scene. + +#### Properties +The Properties panel provides detailed information about the selected object in the scene. Depending on the object type, you can view: +- Coordinates and dimensions +- Colors and intensity values +- Metadata and attributes +- Visibility and rendering settings + +This section gives you full control over the content, allowing you to inspect, modify, or export scene elements efficiently. + + +### About +--- +General information regarding the application, licences, contributors and more will show up here. This is default information from Potree. + +## Minimap +The map icon below the menu bar icon in the top left corner, will show and collapse a minimap. +In the minimap you can zoom using the mouse, touchpad or the icons in the top left corner. +You can move around by clicking and moving the mouse around simultaneously. + +## Coordinates +In the bottom right corner there is a black box that lists coordinates. These coordinates correspond to the target point, which is continuously updated to be the most recent point the user has clicked on. Latitude and longitude are measured in degrees, while elevation is measured in metres from the surface level. \ No newline at end of file diff --git a/src/UserGuide/imagesUserGuide/00_icons.png b/src/UserGuide/imagesUserGuide/00_icons.png new file mode 100644 index 0000000..1aef21c Binary files /dev/null and b/src/UserGuide/imagesUserGuide/00_icons.png differ diff --git a/src/UserGuide/imagesUserGuide/01_menuBarTabs.png b/src/UserGuide/imagesUserGuide/01_menuBarTabs.png new file mode 100644 index 0000000..ac3a94d Binary files /dev/null and b/src/UserGuide/imagesUserGuide/01_menuBarTabs.png differ diff --git a/src/UserGuide/imagesUserGuide/02_ElevationControlTab.png b/src/UserGuide/imagesUserGuide/02_ElevationControlTab.png new file mode 100644 index 0000000..26ef7b1 Binary files /dev/null and b/src/UserGuide/imagesUserGuide/02_ElevationControlTab.png differ diff --git a/src/UserGuide/imagesUserGuide/03_ElevationControlTab.png b/src/UserGuide/imagesUserGuide/03_ElevationControlTab.png new file mode 100644 index 0000000..9b3fcdf Binary files /dev/null and b/src/UserGuide/imagesUserGuide/03_ElevationControlTab.png differ diff --git a/src/UserGuide/imagesUserGuide/04_AcceptedFilter.png b/src/UserGuide/imagesUserGuide/04_AcceptedFilter.png new file mode 100644 index 0000000..ce218ad Binary files /dev/null and b/src/UserGuide/imagesUserGuide/04_AcceptedFilter.png differ diff --git a/src/UserGuide/imagesUserGuide/05_AcceptedFilter.png b/src/UserGuide/imagesUserGuide/05_AcceptedFilter.png new file mode 100644 index 0000000..8dfa909 Binary files /dev/null and b/src/UserGuide/imagesUserGuide/05_AcceptedFilter.png differ diff --git a/src/UserGuide/imagesUserGuide/06_Measurements.png b/src/UserGuide/imagesUserGuide/06_Measurements.png new file mode 100644 index 0000000..d24f47d Binary files /dev/null and b/src/UserGuide/imagesUserGuide/06_Measurements.png differ diff --git a/src/UserGuide/imagesUserGuide/07_SavedLocations.png b/src/UserGuide/imagesUserGuide/07_SavedLocations.png new file mode 100644 index 0000000..31aa2e6 Binary files /dev/null and b/src/UserGuide/imagesUserGuide/07_SavedLocations.png differ diff --git a/src/UserGuide/imagesUserGuide/08_Appearance.png b/src/UserGuide/imagesUserGuide/08_Appearance.png new file mode 100644 index 0000000..ab9f09e Binary files /dev/null and b/src/UserGuide/imagesUserGuide/08_Appearance.png differ diff --git a/src/UserGuide/imagesUserGuide/09_Tools.png b/src/UserGuide/imagesUserGuide/09_Tools.png new file mode 100644 index 0000000..cd259db Binary files /dev/null and b/src/UserGuide/imagesUserGuide/09_Tools.png differ diff --git a/src/UserGuide/imagesUserGuide/10_Scene.png b/src/UserGuide/imagesUserGuide/10_Scene.png new file mode 100644 index 0000000..045067a Binary files /dev/null and b/src/UserGuide/imagesUserGuide/10_Scene.png differ diff --git a/src/UserGuide/imagesUserGuide/11_SavedLocations.png b/src/UserGuide/imagesUserGuide/11_SavedLocations.png new file mode 100644 index 0000000..83153ed Binary files /dev/null and b/src/UserGuide/imagesUserGuide/11_SavedLocations.png differ