source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/Visualization/markertext.xml @ 904

<!-- ******************************************************** -->
<!--                                                          -->
<!--  [History]                                               -->
<!--    Converted to DocBook: Katsuya Amako, Aug-2006         -->
<!--                                                          -->
<!-- ******************************************************** -->


<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.VisPlylMrkTxt">
<title>
Polylines, Markers and Text
</title>

<para>
 Polylines, markers and text are defined in the
<literal>graphics_reps</literal> category, and are used only for
visualization. Here we explain their definitions and usages.
</para>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisPlylMrkTxt.Plyl">
<title>
Polylines
</title>

<para>
A polyline is a set of successive line segments. It is defined with
a class <emphasis>G4Polyline</emphasis> defined in the 
<literal>graphics_reps</literal> category. 
A polyline is used to visualize tracking steps, particle
trajectories, coordinate axes, and any other user-defined objects
made of line segments.
</para>

<para>
<emphasis>G4Polyline</emphasis> is defined as a list of 
<emphasis>G4Point3D</emphasis> objects, i.e., vertex positions. 
The vertex positions are set to a <emphasis>G4Polyline</emphasis> 
object with the <literal>push_back()</literal> method.
</para>

<para>
For example, an x-axis with length 5 cm and with red color is
defined in <xref linkend="programlist_VisPlylMrkTxt_1" />.

<example id="programlist_VisPlylMrkTxt_1">
<title>
Defining an x-axis with length 5 cm and with colour red.
</title>

<programlisting>
 //----- C++ source codes: An example of defining a line segment
// Instantiate an emply polyline object 
G4Polyline  x_axis;

// Set red line colour 
G4Colour         red(1.0, 0.0, 0.0); 
G4VisAttributes  att(red);     
x_axis.SetVisAttributes(&amp;att);

// Set vertex positions
x_axis.push_back( G4Point3D(0., 0., 0.) );
x_axis.push_back( G4Point3D(5.*cm, 0., 0.) );

 //----- end of C++ source codes
</programlisting>
</example>
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisPlylMrkTxt.Mrk">
<title>
Markers
</title>

<para>
Here we explain how to use 3D markers in Geant4 Visualization.
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
What are Markers?
</bridgehead>

<para>
Markers set marks at arbitrary positions in the 3D space. They
are often used to visualize hits of particles at detector
components. A marker is a 2-dimensional primitive with shape
(square, circle, etc), color, and special properties (a) of always
facing the camera and (b) of having the possibility of a size
defined in screen units (pixels). Here "size" means "overall size",
e.g., diameter of circle and side of square (but diameter and
radius access functions are defined to avoid ambiguity).
</para>

<para>
So the user who constructs a marker should decide whether or not
it should be visualized to a given size in world coordinates by
setting the world size. Alternatively, the user can set the screen
size and the marker is visualized to its screen size. Finally, the
user may decide not to set any size; in that case, it is drawn
according to the sizes specified in the default marker specified in
the class <emphasis>G4ViewParameters</emphasis>.
</para>

<para>
By default, "square" and "circle" are supported in Geant4
Visualization. The former is described with class <emphasis>G4Square</emphasis>,
and the latter with class <emphasis>G4Circle</emphasis>:

<informaltable>
  <tgroup cols="2">
    <tbody>
    <row>
      <entry>
        <emphasis role="bold">Marker Type</emphasis>
      </entry>
      <entry>
        <emphasis role="bold">Class Name</emphasis>
      </entry>
    </row>
    <row>
      <entry>
        circle
      </entry>
      <entry>
        <emphasis>G4Circle</emphasis>
      </entry>
    </row>
    <row>
      <entry>
        right square
      </entry>
      <entry>
        <emphasis>G4Square</emphasis>
      </entry>
    </row>
    </tbody>
  </tgroup>
</informaltable>
</para>

<para>
These classes are inherited from class <emphasis>G4VMarker</emphasis>. 
They have constructors as follows:

<informalexample>
<programlisting>
      //----- Constructors of G4Circle and G4Square
      G4Circle::G4Circle (const G4Point3D&amp; pos );
      G4Square::G4Square (const G4Point3D&amp; pos);
</programlisting>
</informalexample>
</para>

<para>
Access functions of class <emphasis>G4VMarker</emphasis> are summarized below.
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Access functions of markers
</bridgehead>

<para>
<xref linkend="programlist_VisPlylMrkTxt_2" /> shows the access functions 
inherited from the base class <emphasis>G4VMarker</emphasis>.

<example id="programlist_VisPlylMrkTxt_2">
<title>
The access functions inherited from the base class
<emphasis>G4VMarker</emphasis>.
</title>

<programlisting>
 //----- Set functions of G4VMarker
 void G4VMarker::SetPosition( const G4Point3D&amp; );
 void G4VMarker::SetWorldSize( G4double );
 void G4VMarker::SetWorldDiameter( G4double );
 void G4VMarker::SetWorldRadius( G4double );
 void G4VMarker::SetScreenSize( G4double );
 void G4VMarker::SetScreenDiameter( G4double );
 void G4VMarker::SetScreenRadius( G4double );
 void G4VMarker::SetFillStyle( FillStyle );
 // Note: enum G4VMarker::FillStyle {noFill, hashed, filled};

 //----- Get functions of G4VMarker
 G4Point3D G4VMarker::GetPosition () const;
 G4double G4VMarker::GetWorldSize () const;
 G4double G4VMarker::GetWorldDiameter () const;
 G4double G4VMarker::GetWorldRadius () const;
 G4double G4VMarker::GetScreenSize () const;
 G4double G4VMarker::GetScreenDiameter () const;
 G4double G4VMarker::GetScreenRadius () const;
 FillStyle G4VMarker::GetFillStyle () const;
 // Note: enum G4VMarker::FillStyle {noFill, hashed, filled};
</programlisting>
</example>
</para>

<para>
<xref linkend="programlist_VisPlylMrkTxt_3" /> shows sample C++ source 
code to define a very small red circle, i.e., a dot with diameter 1.0 pixel. 
Such a dot is often used to visualize a hit.

<example id="programlist_VisPlylMrkTxt_3">
<title>
Sample C++ source code to define a very small red circle.
</title>

<programlisting>
 //----- C++ source codes: An example of defining a red small maker
 G4Circle circle(position); // Instantiate a circle with its 3D
                            // position. The argument "position"
                            // is defined as G4Point3D instance
 circle.SetScreenDiameter (1.0); // Should be circle.SetScreenDiameter
                                 //  (1.0 * pixels) - to be implemented
 circle.SetFillStyle (G4Circle::filled); // Make it a filled circle
 G4Colour colour(1.,0.,0.);              // Define red color
 G4VisAttributes attribs(colour);        // Define a red visualization attribute
 circle.SetVisAttributes(attribs);       // Assign the red attribute to the circle
 //----- end of C++ source codes
</programlisting>
</example>
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.VisPlylMrkTxt.Txt">
<title>
Text
</title>

<para>
Text, i.e., a character string, is used to visualize various kinds
of description, particle name, energy, coordinate names etc. Text
is described by the class <emphasis>G4Text</emphasis> . The following
constructors are supported:

<informalexample>
<programlisting>
     //----- Constructors of G4Text
     G4Text (const G4String&amp; text);
     G4Text (const G4String&amp; text, const G4Point3D&amp; pos);
</programlisting>
</informalexample>

where the argument <literal>text</literal> is the text (string) to be
visualized, and <literal>pos</literal> is the 3D position at which the text
is visualized.
</para>

<para>
Note that class <emphasis>G4Text</emphasis> also inherits <emphasis>G4VMarker</emphasis>.
Size of text is recognized as "font size", i.e., height of the
text. All the access functions defined for class <emphasis>G4VMarker</emphasis>
mentioned above are available. In addition, the following access
functions are available, too:

<informalexample>
<programlisting>
     //----- Set functions of G4Text
     void G4Text::SetText ( const G4String&amp; text ) ;
     void G4Text::SetOffset ( double dx, double dy ) ;

     //----- Get functions of G4Text
     G4String G4Text::GetText () const;
     G4double G4Text::GetXOffset () const;
     G4double G4Text::GetYOffset () const;
</programlisting>
</informalexample>
</para>

<para>
Method <literal>SetText()</literal> defines text to be visualized, and
<literal>GetText()</literal> returns the defined text. Method
<literal>SetOffset()</literal> defines x (horizontal) and y (vertical)
offsets in the screen coordinates. By default, both offsets are
zero, and the text starts from the 3D position given to the
constructor or to the method <literal>G4VMarker:SetPosition()</literal>.
Offsets should be given with the same units as the one adopted for
the size, i.e., world-size or screen-size units.
</para>

<para>
<xref linkend="programlist_VisPlylMrkTxt_4" /> shows sample C++ source code 
to define text with the following properties:

<itemizedlist spacing="compact">
  <listitem><para>
    Text: "Welcome to Geant4 Visualization"
  </para></listitem>
  <listitem><para>
    Position: (0.,0.,0.) in the world coordinates
  </para></listitem>
  <listitem><para>
    Horizontal offset: 10 pixels
  </para></listitem>
  <listitem><para>
    Vertical offset: -20 pixels
  </para></listitem>
  <listitem><para>
    Colour: blue (default)
  </para></listitem>
</itemizedlist>
</para>

<para>
<example id="programlist_VisPlylMrkTxt_4">
<title>
An example of defining text.
</title>

<programlisting>
 //----- C++ source codes: An example of defining a visualizable text

 //----- Instantiation
 G4Text text ;
 text.SetText ( "Welcome to Geant4 Visualization");
 text.SetPosition ( G4Point3D(0.,0.,0.) );
 // These three lines are equivalent to:
 //  G4Text text ( "Welcome to Geant4 Visualization",
 //                 G4Point3D(0.,0.,0.) );

 //----- Size (font size in units of pixels)
 G4double fontsize = 24.; // Should be 24. * pixels - to be implemented.
 text.SetScreenSize ( fontsize );

 //----- Offsets
 G4double x_offset = 10.; // Should be 10. * pixels - to be implemented.
 G4double y_offset = -20.; // Should be -20. * pixels - to be implemented.
 text.SetOffset( x_offset, y_offset );

 //----- Color (Blue is the default setting, and so the codes below are omissible)
 G4Colour blue( 0., 0., 1. );
 G4VisAttributes att ( blue );
 text.SetVisAttributes ( att );

 //----- end of C++ source codes
</programlisting>
</example>
</para>


</sect2>
</sect1>