Mapping graphic space to time space

Time to space mapping refers to the description of relationship between an object local graphic space and its time space. A mapping consists in a set of relations between the two spaces. INScore provides specific messages to describes mappings and to synchronize arbitrary objects i.e. to display their time relationships in the graphic space.

The 'map' message

The map messages can be sent to any address with the form /ITL/scene/\textit{identifier}. It is intended to describe the target object relation to time and sets a relation between an object segmentation and a time segmentation. The global form of the message is:

mapMsg

The relation parameter must be sent as a single string which format is described below. It consists in a list of associations between the object local space and its time space expressed as segments.

relation

Segments are expressed as a list of intervals. For a 1 dimension resource, a segment is a made of a single interval. For a 2 dimensions resource, a segment is a made of 2 intervals: an interval on the x-axis and one on the y-axis for graphic based resource, or an interval on columns and one on lines for text based resources. Intervals are right-opened.

The different kind of relations corresponds to:

  • [1] a relation between a 2 dimensions segmentation expressed in float values and a relative time segmentation. These segmentations are used by rect, ellipse, polygon, curve, line components.
  • [2] a relation between a 2 dimensions segmentation expressed in integer values and a relative time segmentation. These segmentations are used by txt, txtf, img components.
  • [3] a relation between a 1 dimension segmentation expressed in integer values and a relative time segmentation. These segmentations are used by the graph component and express a relation between a signal space and time.

Table maptable summarizes the specific local segmentation used by each component type.

The specified map can be named with an optional mapName string; this name can be further reused, during object synchronization, to specify the mapping to use. When mapName is not specified, the mapping has a default empty name.

The del command deletes the mapping specified with mapName, or the 'empty name' mapping if no map name is specified.

component type segmentation type
txt, txtf int2DSegments
img int2DSegments
rect, ellipse, polygon, curve float2DSegments
graph int1DSegments

Local segmentation type for each component

Segments definitions

timeSegment
relativeTimeSegment
absoluteTimeSegment
float2DSegment
int2DSegment
int1DSegment
relativeTimeInterval
absoluteTimeInterval
floatInterval
intInterval

Relative time is expressed as rational values where 1 represents a whole note.

rational

Absolute time is expressed in minutes, seconds and cents. It is automatically converted to relative time, assuming that the tempo is 60 quarter notes per minute.

absoluteTime

Example Mapping an image graphic space to time:

/ITL/scene/myImage map 
  "( [0, 67[    [0, 86[ ) ( [0/2, 1/2[ ) 
  ( [67, 113[  [0, 86[ ) ( [1/2, 1/1[ ) 
  ( [113, 153[ [0, 86[ ) ( [1/1, 3/2[ ) 
  ( [153, 190[ [0, 86[ ) ( [3/2, 2/1[ ) 
  ( [190, 235[ [0, 86[ ) ( [2/1, 5/2[ )" ;

the image is horizontally segmented into 5 different graphic segments that express pixel positions. The vertical dimension of the segments remains the same and corresponds to the interval [0, 86[. Each graphic segment is associated to a time interval which duration is 1/2 (a half note).

The same mapping using absolute time assumes that 1 second is equal to 1 quarter note:

/ITL/scene/myImage map 
  "( [0, 67[    [0, 86[ )   ( [0:0:0, 0:2:0[ ) 
  ( [67, 113[  [0, 86[ ) ( [0:2:0, 0:4:0[ ) 
  ( [113, 153[ [0, 86[ ) ( [0:4:0, 0:6:0[ ) 
  ( [153, 190[ [0, 86[ ) ( [0:6:0, 0:8:0[ ) 
  ( [190, 235[ [0, 86[ ) ( [0:8:0, 0:10:0[ )" ;

Note: about local spaces

  • Text objects (txt txtf) local space is expressed by intervals on columns and rows.
  • Html object (html, htmlf) do not support mapping because there is not correspondence between the text and the graphic space.
  • Vectorial objects (rect, ellipse, polygon, curve, svg,...) express their local graphic space in internal coordinates system i.e. on the [-1.,1.] interval.
  • Bitmap objects (img) express their local graphic space in pixels.

The 'map+' message

The map+ messages is similar to the map message but doesn't replace the existing mapping data: the specified relations are added to the existing one.

mapAddMsg

Mapping files

The mapf messages is similar to the map message but gives the path name of a file containing the mapping data, along with the optional map name.

mapfMsg

Symbolic score mappings

Mapping between the graphic and time space is automatically computed for symbolic score gmn, gmnstream, gmnf. However and depending on the application, the graphic space may be segmented in different ways, for instance: different graphic segments for different staves, a single graphic segment traversing all a system, etc. Thus for a symbolic score, the map message different and is only intended to select one king mapping supported by the system.

scoreMap
  • page: a page level mapping
  • system: a system level mapping
  • systemflat: a system level mapping without system subdivision (one graphic segment per system)
  • staff_n_: a staff level mapping: the staff number is indicated by n, a number between 1 and the score staves count.
  • voice_n_: a voice level mapping: the voice number is indicated by n, a number between 1 and the score voices count.

The default mapping for a symbolic score is unnamed but equivalent to staff1.

Example Requesting the mapping of the third staff of a score:

/ITL/scene/myScore map staff3;

Requesting the system mapping :

/ITL/scene/myScore map system;

Note: A voice may be distributed on several staves and thus a staff may contain several voices.