<?xml version="1.0"?>

<!-- VACE, Metadata Exchange Interface, Specification -->
<!-- Module Template, Documentation, and DTD -->

<!DOCTYPE module SYSTEM "vace_module_v1_2.dtd">

<module>

<!--
required element # 1: describing what the module is
-->
<module_description
	name="required, documentation"
	version="required, version of a particular module"
	producer="required, contractor, author, etc."
	locator="optional, where the executable is"
	functionality="required, describes specification for this XML"
	other_tags="optional other info like icons for displaying results"
>
	<!-- A module may have more than one executable/operation/step -->
	<operation
		program_name="required, the executable"
		sequence_of_operation="optional, if this module has more than
                                       one executable (step), a number will be
                                       used to specifie the sequence of this
                                       executable"
	>
		<!-- A list of parameters -->
		<param
			name="required, name of the parameter"
			value="optional, value for this parameter"
		/>
	</operation>
</module_description>

<!--
___________________________________________________________
required element # 2: a list of input (videos or images) for this module
-->
<module_input>
	<!-- Range can be specified as time (in msec) or frame number. -->
	<input
		media_type="required, either 'video' or 'image'"
		media_format="required, mpeg1, jpeg, etc."
		media_name="required, file name or others"
		media_locator="optional, where this input is"
		input_id="required, unique id with respect to this XML page"
		time_range="optional, format: 'start:end' time in millisecond"
		frame_range="optional, format: 'start:end' frame number"
		frame_rate="optional, frame rate of video"
	>
		<!-- Specifies zero or more image from a video. -->
		<keyframe
			frame_order="optional, sequence wrt this video"
			time_offset="optional, in millisecond"
			frame_offset="optional, in frame number"
		/>
	</input>
</module_input>

<!--
___________________________________________________________
required element # 3, if data are processed:
a list of detected and/or tracked objects
-->
<module_output>
	<!-- moving_direction is derived from the motion of centroid. -->
	<object
		object_type="text|face|vehicle|human_body"
		object_id="required, unique id with respect to this XML page"
		indexed_text="optional, text will be indexed and searchable"
		label_text="optional, text for display"
		time_range="optional, format: 'start:end' time in millisecond"
		frame_range="optional, format: 'start:end' frame number"
		keyframe_time="optional, keyframe specified in millisecond"
		keyframe_frame="optional, keyframe specified in frame number"
		bounding_box="optional, format:'upper_left_x upper_left_y
                                                lower_right_x lower_left_y'"
		centroid="optional, format:'x y'"
		moving_direction="optional, derived from the motion of
                                  centroids (in 'motion_tracking'); a
                                  SUGGESTED format and unit is in degrees
                                  from 0 to 360; counter-clockwise starting
                                  from 3 o'clock as 0 degree, 12 o'clock as
                                  90 degree, and so on."
		detection_confidence="optional, detection confidence on
				      this object, in percentage"
		recognition_confidence="optional, recognition confidence on
					this object, in percentage"
		input_reference="optional, a reference to an input_id (in the
				 module_input list), which has this object"
	>
		<!-- A list of characteristics for this object -->
		<characteristic
			name="required, name of the characteristic"
			value="optional, value of the characteristic"
		/>
		<!--
		For object tracking, a series of motion_tracking will be used
		to record the locations of an object through time
		-->
		<motion_tracking
			motion_order="required, unique id wrt this object"
			time_range="optional, format: 'start:end' time in msec"
			frame_range="optional, format: 'start:end' frame num"
			bounding_box="optional, format:'upper_left_x
                                      upper_left_y lower_right_x lower_left_y'"
			centroid="optional, format:'x y'"
		/>
	</object>
<!--
EVENT attributes:
event_type:  event type, e.g. human_activity
event_id:  Id identifying the description of an event: It is mostly
	used when an event is a combination of sub_events.
actors_list:  List of objects id involved in the detected event.
	Format: 'object1,object2,.....objectN'
reference_list:  List of objects id representing the reference
	objects. Reference objects are the objects used to describe
	the event.  Format: 'object1,object2,.....objectN'
indexed_text:  Text allowing to index the event
description_text:  Text allowing to describe the event
time_range:  Time range (in milliseconds) of the specified event:
	Format 'start_ms:end_ms'
frame_range:  frame range of the specified event : format
	'start_frame:end_frame'
keyframe_time:  time (in ms)  at which the event was identified
keyframe_frame:  frame at which the event was identified
sub_events:  list of sub-events id involved in the identified event.
	Format: 'event_Id1, event_id2, ...'
temporal_relations:  list of temporal relations between the detected
	sub-events. We identify the following relationships:
	before, after, during. The format is
	'before(event_id1,event_id2);after(event_id1,event_id2);during(event_id1,event_id2)'.
	before(event_id1,event_id2) represents the fact that event_id1
	preceeds event_id2.
-->
	<event
		event_type="required, e.g. human_activity"
		event_id="required, unique id wrt this module_output"
		actors_list="required, 'object_id1,object_id2,...,object_idN'"
		reference_list="required, 'object_id1,...,object_idN'"
		indexed_text="required, text will be indexed and searchable"
		description_text="required, text for display"
		time_range="optional, format: 'start:end' time in millisecond"
		frame_range="optional, format: 'start:end' frame number"
		keyframe_time="optional, keyframe specified in millisecond"
		keyframe_frame="optional, keyframe specified in frame number"
		sub_events="optional, 'event_id1,event_id2,...,event_idN'"
		temporal_relations="optional,
			'before(event_list);after(event_list);during(event_list)'
			where event_list is 'event_id1,...,event_idN'"
	/>
</module_output>

<!--
___________________________________________________________
required element # 4, if data are processed:
recording how this module finishes processing
-->
<processing_status
	date_processed="required, the date that this module is applied"
	exit_status="optional, indicates how the process is terminated"
/>

<!--
___________________________________________________________
optional element # 1:
Elements and attributes will be built on those of 'object' element.
This is an open-end element, which is subjected to the availability of
intermediate, new, or not-yet-discovered output.
-->
<contributive_output>
</contributive_output>

<!--
___________________________________________________________
optional element # 2:
Elements and attributes will be built on those of 'input' element.
This is an open-end element, which is subjected to the requirement of
other data or not-yet-discovered/determined processing need.
-->
<auxiliary_input_suggestion>
</auxiliary_input_suggestion>

</module>

