orthanc-stone: OrthancStone/Resources/Documentation/stone-object-model-reference.md annotate

annotate OrthancStone/Resources/Documentation/stone-object-model-reference.md @ 1829:1623146decea

todo

author	Sebastien Jodogne <s.jodogne@gmail.com>
date	Thu, 27 May 2021 11:19:38 +0200
parents	b5417e377636
children

rev	line source
1322 0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	1 ## Scene2D and viewport-related object reference
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	2
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	3 ### `Scene2D`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	4
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	5 Represents a collection of layers that display 2D data.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	6
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	7 These layers must implement `ISceneLayer`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	8
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	9 The layers must be created externally and set to a specific Z-order index
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	10 with the `SetLayer` method.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	11
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	12 The `Scene2D` object merely acts as a layer container. It has no rendering
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	13 or layer creation facility on its own.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	14
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	15 The `Scene2D` contains an `AffineTransform2D` structure that defines how
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	16 the various layer item coordinates are transformed before being displayed
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	17 on the viewport (aka canvas)
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	18
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	19 It is up to each layer type-specific renderer to choose how this transformation
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	20 is used. See the various kinds of layer below for more details.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	21
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	22 Examining the `Scene2D` contents can be done either by implementing the
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	23 `Scene2D::IVisitor` interface and calling `Apply(IVisitor& visitor)` or by
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	24 iterating between `GetMinDepth()` and `GetMaxDepth()` and calling the
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	25 `ISceneLayer& GetLayer(int depth)` getter.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	26
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	27 ### `ISceneLayer`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	28
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	29 Interface that must be implemented by `Scene2D` layers. This is a closed list
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	30 that, as of 2020-03, contains:
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	31
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	32 ```
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	33 Type_InfoPanel,
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	34 Type_ColorTexture,
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	35 Type_Polyline,
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	36 Type_Text,
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	37 Type_FloatTexture,
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	38 Type_LookupTableTexture
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	39 ```
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	40
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	41 Please note that this interface mandates the implementation of a `GetRevision`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	42 method returning an `uint64_t`.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	43
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	44 The idea is that when a model gets converted to a set of `ISceneLayer`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	45 instances, changes in the model that result in changes to the layers must
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	46 increase the revision number of these layers.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	47
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	48 That allows the rendering process to safely assume that a given layers whose
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	49 revision does not change hasn't been modified (this helps with caching).
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	50
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	51 Every mutable method in `ISceneLayer` instances that possibly change the visual
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	52 representation of an `ISceneLayer` must increase this revision number.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	53
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	54 ### Implementation: `FloatTextureSceneLayer`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	55
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	56 Layer that renders an `Orthanc::ImageAccessor` object that must be convertible
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	57 to `Float32` image.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	58
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	59 The constructor only uses the image accessor to perform a copy. It can safely
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	60 be deleted afterwards.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	61
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	62 The input values are mapped to the output values by taking into account various
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	63 properties that can be modified with:
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	64
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	65 - `SetWindowing`: uses windowing presets like "bone" or "lung"
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	66 - `SetCustomWindowing`: with manual window center and width
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	67 - `SetInverted`: toggles black <-> white inversion after windowing
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	68 - `SetApplyLog`: uses a non-linear response curve described in
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	69 https://theailearner.com/2019/01/01/log-transformation/ that expands contrast
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	70 in dark areas while compressing contrast in bright ones. This is not
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	71 implemented in the OpenGL renderer!
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	72
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	73 The corresponding renderers are `OpenGLFloatTextureRenderer` and
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	74 `CairoFloatTextureRenderer`. The scene transformation is applied during
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	75 rendering.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	76
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	77 ### Implementation: `ColorTextureSceneLayer`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	78
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	79 Layer that renders an `Orthanc::ImageAccessor` object an RGBA image (alpha must
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	80 be premultiplied).
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	81
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	82 The constructor only uses the image accessor to perform a copy. It can safely
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	83 be deleted afterwards.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	84
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	85 The corresponding renderers are `OpenGLColorTextureRenderer` and
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	86 `CairoColorTextureRenderer`. The scene transformation is applied during
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	87 rendering.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	88
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	89 ### Implementation: `LookupTableTextureSceneLayer`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	90
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	91 Layer that renders an `Orthanc::ImageAccessor` object that must be convertible
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	92 to `Float32` image.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	93
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	94 The constructor only uses the image accessor to perform a copy. It can safely
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	95 be deleted afterwards.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	96
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	97 The final on-screen color of each pixel is determined by passing the input
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	98 `Float32` value through a 256-entry look-up table (LUT) that can be passed as
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	99 an array of either 256 x 3 bytes (for opaque RGB colors) or 256 x 4 bytes (for
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	100 RGBA pixels). The LUT is not specified at construction time, but with
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	101 calls to `SetLookupTable` or `SetLookupTableGrayscale` (that fills the LUT
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	102 with a gradient from black to white, fully opaque)
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	103
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	104 The range of input values that is mapped to the entirety of the LUT is, by
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	105 default, the full image range, but can be customized with `SetRange`.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	106
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	107 The corresponding renderers are `OpenGLLookupTableTextureRenderer` and
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	108 `CairoLookupTableTextureRenderer`. The scene transformation is applied during
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	109 rendering.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	110
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	111 ### Implementation: `PolylineSceneLayer`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	112
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	113 Layer that renders vector-based polygonal lines.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	114
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	115 Polylines can be added with the `AddChain` method, that accepts a `Chain`, that
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	116 is a typedef to `std::vector<ScenePoint2D>`, a flag to specify whether the
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	117 chain must be automatically close (last point of the vector connected to the
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	118 first one) and the chain color (a `Color` structure).
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	119
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	120 Please note that the line thickness is, contrary to the color, specified
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	121 per-chain but rather per-layer.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	122
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	123 If you need multiple line thicknesses, multiple `PolylineSceneLayer` must be
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	124 created.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	125
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	126 The corresponding renderers are `OpenGLAdvancedPolylineRenderer` and
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	127 `CairoPolylineRenderer`. The scene transformation is applied during
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	128 rendering.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	129
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	130 ### Implementation: `TextSceneLayer`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	131
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	132 This layers renders a paragraph of text.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	133
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	134 The inputs to the layer can be changed after creation and are:
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	135 - The text iself, supplied as an UTF-8 encoded string in `SetText`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	136 - The font used for rendering, set by `SetFontIndex`.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	137 - The text anchoring, through `SetAnchor`: the text can be anchored to
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	138 various positions, such as top lef, center, bottom center,... These
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	139 various anchors are part of the `BitmapAnchor` enumeration.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	140 - The text position, relative to its anchor, through `SetPosition`.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	141
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	142 The font is supplied as an index. This is an index in the set of fonts
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	143 that has been registered in the viewport compositor. The following code
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	144 shows how to set such a font:
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	145
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	146 ```
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	147 std::unique_ptr<OrthancStone::IViewport::ILock> lock(viewport_.Lock());
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	148 lock->GetCompositor().SetFont(0,
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	149 Orthanc::EmbeddedResources::UBUNTU_FONT,
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	150 32, Orthanc::Encoding_Latin1);
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	151 // where 32 is the font size in pixels
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	152 ```
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	153
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	154 This call uses the embedded `UBUNTU_FONT` resource that has been defined in
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	155 the `CMakeLists.txt` file with:
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	156
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	157 ```
1471 28c64c246312 working on a shared library Sebastien Jodogne <s.jodogne@gmail.com> parents: 1365 diff changeset	158 EmbedResources(
1322 0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	159 UBUNTU_FONT ${CMAKE_BINARY_DIR}/ubuntu-font-family-0.83/Ubuntu-R.ttf
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	160 )
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	161 ```
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	162
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	163 Please note that you must supply a font: there is no default font provided by
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	164 the OpenGL or Cairo compositors.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	165
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	166 The corresponding renderers are `OpenGLTextRenderer` and
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	167 `CairoTextRenderer`. The scene transformation is not applied during rendering,
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	168 because the text anchoring, position and scaling are computed relative to the
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	169 viewport/canvas.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	170
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	171 ### Implementation: `InfoPanelSceneLayer`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	172
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	173 This layer is designed to display an image, supplied through an
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	174 `Orthanc::ImageAccessor` reference (only used at construction time).
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	175
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	176 The image is not transformed according to the normal layer transformation but
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	177 is rather positioned relative to the canvas, with the same mechanism as the
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	178 `TextSceneLayer` described above.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	179
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	180 The image position is specified with the sole means of the `SetAnchor` method.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	181
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	182 The corresponding renderers are `OpenGLInfoPanelRenderer` and
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	183 `CairoInfoPanelRenderer`.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	184
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	185 ### `IViewport`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	186
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	187 https://bitbucket.org/sjodogne/orthanc-stone/src/broker/Framework/Viewport/IViewport.h
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	188
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	189 (not the one in `Deprecated`)
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	190 - Implemented by classes that:
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	191 - manage the on-screen display of a `Scene2D` trough a compositor.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	192 - Own the `ICompositor` object that performs the rendering.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	193 - Own the `Scene2D` (TODO: currently through `ViewportController` --> `Scene2D`)
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	194 - Provide a `Lock` method that returns a RAII, that must be kept alive when
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	195 modifying the underlying objects (controller, compositor, scene), but not
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	196 longer.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	197
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	198 #### Implementation: `SdlOpenGLViewport`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	199 - Implementation of a viewport rendered on a SDL window, that uses OpenGL for
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	200 rendering.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	201 - Instantiating this object creates an SDL window. Automatic scaling for hiDPI
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	202 displays can be toggled on or off.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	203
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	204 #### Implementation: `WebGLViewport`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	205 - Implementation of a viewport rendered on a DOM canvas, that uses OpenGL for
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	206 rendering.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	207 - Contrary to the SDL OpenGL viewport, the canvas must already be existing
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	208 when the ctor is called.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	209
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	210 ### `ICompositor`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	211 The interface providing a rendering service for `Scene2D` objects.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	212
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	213 Subclasses: `CairoCompositor`, `OpenGLCompositor`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	214
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	215 You do not need to create compositor instances. They are created for you when
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	216 instantiating a viewport.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	217
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	218 ### `ViewportController`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	219 This concrete class is instantiated by its `IViewport` owner.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	220
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	221 TODO: its functionality is not well defined and should be moved into the
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	222 viewport base class. Support for measuring tools should be moved to a special
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	223 interactor.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	224
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	225 - contains:
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	226 - array of `MeasureTool`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	227 - ref to `IViewport`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	228 - `activeTracker_`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	229 - owns a `Scene2D`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	230 - weak ref to `UndoStack`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	231 - cached `canvasToSceneFactor_`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	232
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	233 - contains logic to:
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	234 - pass commands to undostack (trivial)
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	235 - logic to locate `MeasureTool` in the HitTest
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	236 - OTOH, the meat of the measuring tool logic (highlighting etc..) is
1365 c7d98d750224 reduce verbosity + some comments Benjamin Golinvaux <bgo@osimis.io> parents: 1322 diff changeset	237 done in app-specific code (`VolumeSlicerWidget`)
1322 0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	238 - accept new Scene transform and notify listeners
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	239 - the code that uses the interactor (`HandleMousePress`) is only
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	240 called by the new `WebAssemblyViewport` !!! TODO clean this mess
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	241
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	242 ### `IViewportInteractor`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	243 - must provide logic to respond to `CreateTracker`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	244
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	245 ### `DefaultViewportInteractor`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	246 - provides Pan+Rotate+Zoom trackers
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	247
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	248 ### `WebGLViewportsRegistry`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	249
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	250 This class is a singleton (accessible through `GetWebGLViewportsRegistry()`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	251 that deals with context losses in the WebGL contexts.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	252
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	253 You use it by creating a WebGLViewport in the following fashion:
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	254
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	255 ```
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	256 boost::shared_ptr<OrthancStone::WebGLViewport> viewport(
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	257 OrthancStone::GetWebGLViewportsRegistry().Add(canvasId));
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	258 ```
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	259
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	260 ## Source data related
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	261
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	262 ### `IVolumeSlicer`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	263
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	264 A very simple interface with a single method:
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	265 `IVolumeSlicer::IExtractedSlice* ExtractSlice(const CoordinateSystem3D& cuttingPlane)`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	266
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	267 ### `IVolumeSlicer::IExtractedSlice`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	268
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	269 On a slice has been extracted from a volume by an `IVolumeSlicer`, it can
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	270 report its revision number.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	271
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	272 If another call to `ExtractSlice` with the same cutting plane is made, but
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	273 the returned slice revision is different, it means that the volume has
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	274 changed and the scene layer must be refreshed.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	275
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	276 Please see `VolumeSceneLayerSource::Update` to check how this logic is
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	277 implemented.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	278
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	279
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	280 ### `OrthancSeriesVolumeProgressiveLoader`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	281
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	282 This class implements `IVolumeSlicer` (and `IObservable`) and can be used to
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	283 load a volume stored in a Dicom series on an Orthanc server.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	284
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	285 Over the course of the series loading, various notifications are sent:
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	286
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	287 The first one is `OrthancStone::DicomVolumeImage::GeometryReadyMessage` that
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	288 is sent when the volume extent and geometric properties are known.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	289
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	290 Then, as slices get loaded and the volume is filled,
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	291 `OrthancStone::DicomVolumeImage::ContentUpdatedMessage` are sent.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	292
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	293 Once all the highest-quality slices have been loaded, the
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	294 `OrthancSeriesVolumeProgressiveLoader::VolumeImageReadyInHighQuality`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	295 notification is sent.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	296
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	297 Please note that calling `ExtractSlice` before the geometry is loaded will
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	298 yield an instance of `InvalidSlice` that cannot be used to create a layer.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	299
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	300 On the other hand,
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	301
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	302 ### `VolumeSceneLayerSource`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	303
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	304 This class makes the bridge between a volume (supplied by an `IVolumeSlicer`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	305 interface) and a `Scene2D`.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	306
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	307 Please note that the bulk of the work is done the objects implementing
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	308 `IVolumeSlicer` and this object merely connects things together.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	309
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	310 For instance, deciding whether an image (texture) or vector (polyline) layer
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	311 is done by the `IVolumeSlicer` implementation.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	312
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	313 - contains:
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	314 - reference to Scene2D
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	315 - `layerIndex_` (fixed at ctor) that is the index, in the Scene2D layer
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	316 stack, of the layer that will be created/updated
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	317 - `IVolumeSlicer`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	318
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	319 - contains logic to:
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	320 - extract a slice from the slicer and set/refresh the Scene2D layer at
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	321 the supplied `layerIndex_`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	322 - refresh this based on the slice revision or configuration revision
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	323 - accept a configuration that will be applied to the layer
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	324 - the `Update()` method will
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	325
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	326 ## Updates and the configurators
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	327
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	328 `ISceneLayer` does not expose mutable methods.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	329
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	330 The way to change a layer once it has been created is through configurator
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	331 objets.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	332
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	333 If you plan to set (even only once) or modify some layer properties after
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	334 layer creation, you need to create a matching configurator objet.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	335
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	336 For instance, in the `VolumeSceneLayerSource`, the `SetConfigurator` method
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	337 will store a `ILayerStyleConfigurator* configurator_`.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	338
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	339 In the `OrthancView` ctor, you can see how it is used:
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	340
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	341 ```
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	342 std::unique_ptr<GrayscaleStyleConfigurator> style(
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	343 new GrayscaleStyleConfigurator);
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	344
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	345 style->SetLinearInterpolation(true);
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	346
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	347 ...<some more code>...
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	348
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	349 std::unique_ptr<LookupTableStyleConfigurator> config(
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	350 new LookupTableStyleConfigurator);
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	351
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	352 config->SetLookupTable(Orthanc::EmbeddedResources::COLORMAP_HOT);
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	353
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	354 ```
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	355
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	356 The configurator type are created according to the type of layer.¸
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	357
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	358 Later, in `VolumeSceneLayerSource::Update(const CoordinateSystem3D& plane)`,
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	359 if the cutting plane has not changed and if the layer revision has not
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	360 changed, we test `configurator_->GetRevision() != lastConfiguratorRevision_`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	361 and, if different, we call `configurator_->ApplyStyle(scene_.GetLayer(layerDepth_));`
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	362
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	363 This allows to change layer properties that do not depend on the layer model
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	364 contents.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	365
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	366 On the other hand, if the layer revision has changed, when compared to the
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	367 last time it has been rendered (stored in `lastRevision_`), then we need to
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	368 ask the slice to create a brand new layer.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	369
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	370 Another way to see it is that layer rendering depend on model data and view
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	371 data. The model data is not mutable in the layer and, if the model changes, the
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	372 layer must be recreated.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	373
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	374 If only the view properties change (the configurator), we call ApplyStyle
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	375 (that will mutate some of the layer internals)
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	376
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	377 Please note that the renderer does not know about the configurator : the
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	378 renderer uses properies in the layer and does not care whether those have
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	379 been set once at construction time or at every frame (configuration time).
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	380
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	381
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	382 ## Cookbook
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	383
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	384 ### Simple application
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	385
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	386 #### Building
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	387
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	388 In order to create a Stone application, you need to:
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	389
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	390 - CMake-based application:
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	391 ```
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	392 include(${STONE_SOURCES_DIR}/Resources/CMake/OrthancStoneConfiguration.cmake)
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	393 ```
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	394 with this library target that you have to define:
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	395 ```
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	396 add_library(OrthancStone STATIC ${ORTHANC_STONE_SOURCES})
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	397 ```
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	398 then link with this library:
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	399 ```
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	400 target_link_libraries(MyStoneApplication OrthancStone)
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	401 ```
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	402
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	403 Building is supported with emscripten, Visual C++ (>= 9.0), gcc...
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	404
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	405 emscripten recommended version >= 1.38.41
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	406
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	407 These are very rough guidelines. See the `Samples` folder for actual examples.
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	408
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	409 #### Structure
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	410
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	411 The code requires a loader (object that )
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	412
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	413 Initialize:
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	414
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	415 ```
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	416 Orthanc::Logging::Initialize();
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	417 Orthanc::Logging::EnableInfoLevel(true);
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	418 ```
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	419 Call, in WASM:
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	420 ```
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	421 DISPATCH_JAVASCRIPT_EVENT("StoneInitialized");
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	422 ```
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	423
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	424 # Notes
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	425
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	426 - It is NOT possible to abandon the existing loaders : they contain too much loader-specific getters
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	427
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	428
0da659f8579c Object reference 1st commit + indent change Benjamin Golinvaux <bgo@osimis.io> parents: diff changeset	429

Mercurial > hg > orthanc-stone

annotate OrthancStone/Resources/Documentation/stone-object-model-reference.md @ 1829:1623146decea