<commit_before>==========
User guide
==========

Navigation
----------

Displaz uses three mouse buttons to control the 3D view:

* *Rotate* the view by dragging with the left mouse button
* *Centre* the camera on the closest point under the mouse by clicking the middle mouse button
* *Zoom* by dragging with the right mouse button (or with the mouse wheel)

To change how points are displayed, use the controls in the *Shader Parameters*
box on the right hand side of the screen.  For example, to change the point
radius, click and *vertically drag* the arrows of the spinbox labelled "Point
Radius" (yes, this is nonstandard; it is also very useful).  To view any colour
channel present, select "Colour" from the "Colour Mode" drop down box.

Various information is available in the *Log* box on the bottom right,
including attributes of selected points, file load errors, and so forth.

The *Data Sets* box shows a list of all currently loaded data sets, allowing
the visibility to be controlled.  A selected data set may be unloaded by
pressing the delete key.


Shader editing
--------------

Displaz allows full control over how points are displayed in the 3D window by
allowing the user to edit and recompile the shader program which is accessible
via *View->Shader Editor*.  Shaders are written in the OpenGL shading language
with some extra hints in GLSL comments describing how to connect shader
variables to the controls in the *Shader Parameters* dialog box.  After editing
a shader, pressing *Shift+Return* will cause the shader to be recompiled and
the 3D view updated.

As a fairly minimal example, consider the file ``simple_example.glsl`` from the
shaders directory:

.. include:: ../shaders/simple_example.glsl
  :literal:

Each shader source file consists of both a vertex and fragment shader,
distinguished by use of the ``VERTEX_SHADER`` and ``FRAGMENT_SHADER`` macros.

At the least, the vertex shader should perform a perspective transformation to
set the built in ``gl_Position`` and ``gl_PointSize`` variables as shown.  If
you're interested in a nontrivial colour, you should also set a colour output
variable which will need to match a colour input variable in the fragment shader.

The fragment shader must set a per pixel colour - in this case it is inherited
very simply from the vertex shader.  It can also decide to discard fragments so
that point shapes other than squares can be created (see for example the
default shader ``las_points.glsl`` in the shaders directory.)<commit_msg>Link from userguide.rst to simple_example.glsl<commit_after>==========
User guide
==========

Navigation
----------

Displaz uses three mouse buttons to control the 3D view:

* *Rotate* the view by dragging with the left mouse button
* *Centre* the camera on the closest point under the mouse by clicking the middle mouse button
* *Zoom* by dragging with the right mouse button (or with the mouse wheel)

To change how points are displayed, use the controls in the *Shader Parameters*
box on the right hand side of the screen.  For example, to change the point
radius, click and *vertically drag* the arrows of the spinbox labelled "Point
Radius" (yes, this is nonstandard; it is also very useful).  To view any colour
channel present, select "Colour" from the "Colour Mode" drop down box.

Various information is available in the *Log* box on the bottom right,
including attributes of selected points, file load errors, and so forth.

The *Data Sets* box shows a list of all currently loaded data sets, allowing
the visibility to be controlled.  A selected data set may be unloaded by
pressing the delete key.


Shader editing
--------------

Displaz allows full control over how points are displayed in the 3D window by
allowing the user to edit and recompile the shader program which is accessible
via *View->Shader Editor*.  Shaders are written in the OpenGL shading language
with some extra hints in GLSL comments describing how to connect shader
variables to the controls in the *Shader Parameters* dialog box.  After editing
a shader, pressing *Shift+Return* will cause the shader to be recompiled and
the 3D view updated.

As a fairly minimal example, consider the file
`simple_example.glsl <../shaders/simple_example.glsl>`_
from the shaders directory.

.. include:: ../shaders/simple_example.glsl
  :literal:

Each shader source file consists of both a vertex and fragment shader,
distinguished by use of the ``VERTEX_SHADER`` and ``FRAGMENT_SHADER`` macros.

At the least, the vertex shader should perform a perspective transformation to
set the built in ``gl_Position`` and ``gl_PointSize`` variables as shown.  If
you're interested in a nontrivial colour, you should also set a colour output
variable which will need to match a colour input variable in the fragment shader.

The fragment shader must set a per pixel colour - in this case it is inherited
very simply from the vertex shader.  It can also decide to discard fragments so
that point shapes other than squares can be created (see for example the
default shader ``las_points.glsl`` in the shaders directory.)
{'fraction_non_alphanumeric': 0.06219344712576025, 'fraction_numerical': 0.0011771630370806356, 'mean_word_length': 4.377637130801688, 'pattern_counts': {'":': 0, '<': 4, '<?xml version=': 0, '>': 6, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '869604', 'n_tokens_mistral': 1303, 'n_tokens_neox': 1239, 'n_words': 780}