viper.descriptors.attributes
Class FrameSpan

java.lang.Object
  viper.descriptors.attributes.FrameSpan

All Implemented Interfaces:

java.lang.Cloneable, Composable, Filterable, Measurable

public class FrameSpan

extends java.lang.Object

implements java.lang.Cloneable, Filterable, Composable, Measurable

This class represents the numeric span of frames in a video, consisting of the beginning and end frame and a bitmask on all frames in between, as well as several actions upon them, such as intersection, union, and size. Frame indexes cannot fall below zero.

Author:

davidm

Nested Class Summary

Nested classes inherited from class viper.filters.Filterable

Filterable.Rule

Nested classes inherited from class viper.descriptors.attributes.Measurable

Measurable.Difference

Field Summary

static double

alpha The factor used to apply to the extents distance exponent when converting it from an unbounded number to the range from zero to one.

Fields inherited from interface viper.descriptors.attributes.Composable

ORDERED, UNORDERED

Constructor Summary

FrameSpan()
Default constructor; returns an empty framespan.

FrameSpan(int start, int finish)
Initializes a new FrameSpan with specified bounds.

Method Summary

int	beginning() Returns the index of the first frame of this FrameSpan.
void	clear(int frameNumber) Clears the specified frame.
void	clear(int start, int stop) Removes all frames in the range start to stop, inclusive.
java.lang.Object	clone() Returns a copy of the FrameSpan.
boolean	coincide(FrameSpan other, int tolerance) Determines if this span and another's bounds are within a certain tolerance
Composable	compose(Composable partner) Generate the composition of this object with its partner.
boolean	containsFrame(int frameNumber) Tests to see if a given frame is contained in this FrameSpan.
Filterable.Rule	convertRule(java.lang.String unparsedRule, java.util.List unparsedValues, ErrorWriter err) This converts a string into a rule, writing out errors in the format to err.
int	ending() Returns the index of the end frame of this FrameSpan.
boolean	equals(FrameSpan other) Tests the equality of two FrameSpans.
int	extents(FrameSpan other) Returns the sum of the absolute values of the differences between the beginning and ending points of this FrameSpan object and another.
int	getCompositionType() Get the type of composition to try.
Measurable.Difference	getDifference(Measurable beta, Measurable blackout, Measurable ignore, CanonicalFileDescriptor cfd) Not optimized version.
Measurable.Difference	getDifference(Measurable beta, Measurable blackout, Measurable ignore, CanonicalFileDescriptor cfd, Measurable.Difference old) For performance reasons, takes an optional (could be null) Measurable.Difference to replace the data from.
java.lang.String	getType() Gets the type name.
int	hashCode() Gets the hash code as the xor of the first and last frames, and the internal bit mask.
FrameSpan	intersect(FrameSpan other) Returns the span that is shared between this and the other.
boolean	intersects(FrameSpan other) Tests to see if this span intersects with the other.
void	intersectWith(FrameSpan other) Removes all frames in this frame span not present in the other frame span.
boolean	isContiguous() Determines if the span is contiguous.
boolean	isEmpty() Tests to see if there are any frames in this frame span.
boolean	isValidRule(java.lang.String ruleName) Tell if a name is a valid rule or not
FrameSpan	minus(FrameSpan other) Returns this span withou any frames in the other.
int	numFrames() Counts the number of active frames in this FrameSpan.
double	overlap(FrameSpan other) Calculates the overlap of another FrameSpan with this one.
static FrameSpan	parseFrameSpan(java.lang.String S) Reads a String in and parses it.
boolean	passes(Filterable.Rule rule) Tests to see if the value passes the given rule.
void	set(int frameNumber) Sets the specified frame to active.
void	shift(int offset) Shifts all frames by the specified offset.
int	size() Returns the total number of frames included in the span.
java.util.List	split() Returns a list of non-adjacent, individually contiguous FrameSpan objects from a single disjoint framespan.
java.lang.String	toString() Returns a String representing the FrameSpan.
FrameSpan	union(FrameSpan other) Returns the span that is shared between the first beginning and the last end.

Methods inherited from class java.lang.Object

equals, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

alpha

public static double alpha

The factor used to apply to the extents distance exponent when converting it from an unbounded number to the range from zero to one.

Constructor Detail

FrameSpan

public FrameSpan()

Default constructor; returns an empty framespan.

FrameSpan

public FrameSpan(int start,
                 int finish)

Initializes a new FrameSpan with specified bounds. All frames within and including the bounds are set.

Parameters:

start - the index of the first frame

finish - the index of the last frame

Method Detail

isEmpty

public boolean isEmpty()

Tests to see if there are any frames in this frame span.

Returns:

if a frame is in this frame span

hashCode

public int hashCode()

Gets the hash code as the xor of the first and last frames, and the internal bit mask.

Returns:

equals

public boolean equals(FrameSpan other)

Tests the equality of two FrameSpans. First compares the Beginning and End frame number, then each individual frame.

Parameters:

other - the span to compare with

Returns:

true only if this and the specified span refer to the same set of frames.

intersects

public boolean intersects(FrameSpan other)

Tests to see if this span intersects with the other.

Parameters:

other - the span to check

Returns:

true if there is a shared frame

intersect

public FrameSpan intersect(FrameSpan other)

Returns the span that is shared between this and the other.

 
           |---------- ---|
                   |---- -----|
  becomes:         |-- - -|
  
 

Parameters:

other - The FrameSpan that this is to be intersected with.

Returns:

The span that the two share.

minus

public FrameSpan minus(FrameSpan other)

Returns this span withou any frames in the other.

 
          |---------- ---|
                   |---- -----|
  becomes: |------|     H
  
 

Parameters:

other - The FrameSpan to remove from this

Returns:

Equivalent to looping through all of the frames of other and calling clear(int)for each valid frame.

intersectWith

public void intersectWith(FrameSpan other)

Removes all frames in this frame span not present in the other frame span.

Parameters:

other - the span to intersect with

union

public FrameSpan union(FrameSpan other)

Returns the span that is shared between the first beginning and the last end. That is:

 
           |---- ----- - --|
                   |-- --- ----|
  becomes: |---- ----- --------|
  
 

and

 
           |---------|
                          |----------|
  becomes: |----------    -----------|
  
 

Parameters:

other - - the FrameSpan that this is to be unioned with

Returns:

the span covered by either or between both

shift

public void shift(int offset)

Shifts all frames by the specified offset. For example, if this framespan represents frames 100 through 150 and it is shifted by -75, it will then represent frames 25 through 75. This is useful for encoding several different DescVectors into one DescVector.

Parameters:

offset - the number of frames to shift the span by

Throws:

java.lang.IndexOutOfBoundsException - if there is a negative frame

size

public int size()

Returns the total number of frames included in the span. Counts both active and inactive frames.

Returns:

The length of the frame (ending- beginning+ 1).

clone

public java.lang.Object clone()

Returns a copy of the FrameSpan.

Returns:

A new FrameSpan object equal to the original.

toString

public java.lang.String toString()

Returns a String representing the FrameSpan.

Returns:

Either the standard output, or a comma seperated list of FrameSpans in the standard output format, like "1:5, 7:10", to indicate a span from 1:10 that is missing frame 6.

parseFrameSpan

public static FrameSpan parseFrameSpan(java.lang.String S)
                                throws BadDataException

Reads a String in and parses it. The format looks like Start Frame:End Frame, eg "1:1" or "10:1000". Please note that you might have to write your own parse function to read the toStringmethod's output, probably by using a StringTokenizer or the like.

Parameters:

S - the FrameSpan string. Must be in the form ##:##

Returns:

a new FrameSpan object that covers the frames the String specified

Throws:

BadDataException - if the data is malformed

coincide

public boolean coincide(FrameSpan other,
                        int tolerance)

Determines if this span and another's bounds are within a certain tolerance

Parameters:

other - FrameSpan to compare this FrameSpan with.

tolerance - Integer value representing the number of frames each terminating frame is allowed from truth.

Returns:

true if they are within the tolerance.

overlap

public double overlap(FrameSpan other)

Calculates the overlap of another FrameSpan with this one.

Parameters:

other - The FrameSpan to compare this with.

Returns:

(the number of frames in the intersection) / (the number of frames in this)

numFrames

public int numFrames()

Counts the number of active frames in this FrameSpan.

Returns:

the number of frames that are active in the specified span

containsFrame

public boolean containsFrame(int frameNumber)

Tests to see if a given frame is contained in this FrameSpan.

Parameters:

frameNumber - The index to find.

Returns:

true if the frame is set.

extents

public int extents(FrameSpan other)

Returns the sum of the absolute values of the differences between the beginning and ending points of this FrameSpan object and another.

Parameters:

other - The FrameSpan to compare with this.

Returns:

The sum of the absolute values of the extents.

ending

public int ending()

Returns the index of the end frame of this FrameSpan.

Returns:

The index of the last frame.

beginning

public int beginning()

Returns the index of the first frame of this FrameSpan.

Returns:

The index of the first frame.

set

public void set(int frameNumber)

Sets the specified frame to active.

Parameters:

frameNumber - the index of the frame to set. If out of this FrameSpan's boundary, it will increase in size to accomidate.

Throws:

java.lang.IndexOutOfBoundsException - if the frame is negative

isContiguous

public boolean isContiguous()

Determines if the span is contiguous. Empty framespans are defined as contiguous.

Returns:

true if the span contains all frames in its extent

split

public java.util.List split()

Returns a list of non-adjacent, individually contiguous FrameSpan objects from a single disjoint framespan. They are in order.

Returns:

a list of contiguous framespans that, together, construct this one

clear

public void clear(int start,
                  int stop)

Removes all frames in the range start to stop, inclusive.

Parameters:

start - the first frame to remove

stop - the last frame to remove

clear

public void clear(int frameNumber)

Clears the specified frame.

Parameters:

frameNumber - resets the specified frame

convertRule

public Filterable.Rule convertRule(java.lang.String unparsedRule,
                                   java.util.List unparsedValues,
                                   ErrorWriter err)
                            throws BadDataException

Description copied from interface: Filterable

This converts a string into a rule, writing out errors in the format to err.

Specified by:

convertRule in interface Filterable

Parameters:

unparsedRule - A string containing a single rule.

unparsedValues - A string containing values.

err - A place to log the errors.

Returns:

A List containing a rule (String) and value (Object) pair.

Throws:

BadDataException

isValidRule

public boolean isValidRule(java.lang.String ruleName)

Description copied from interface: Filterable

Tell if a name is a valid rule or not

Specified by:

isValidRule in interface Filterable

Parameters:

ruleName - the name of the rule

Returns:

true if the rule is valid.

getCompositionType

public int getCompositionType()

Description copied from interface: Composable

Get the type of composition to try.

Specified by:

getCompositionType in interface Composable

Returns:

Composable.UNORDERED

getType

public java.lang.String getType()

Description copied from interface: Measurable

Gets the type name.

Specified by:

getType in interface Measurable

Returns:

" framespan"

getDifference

public Measurable.Difference getDifference(Measurable beta,
                                           Measurable blackout,
                                           Measurable ignore,
                                           CanonicalFileDescriptor cfd)
                                    throws IgnoredValueException

Description copied from interface: Measurable

Not optimized version. Usually will just call getDifference (..., null).

Specified by:

getDifference in interface Measurable

Parameters:

beta - the value to subtract/get the difference from

blackout - the bad region

ignore - the ignored region

cfd - the media's information

Returns:

the difference between this and beta, given the constraints

Throws:

IgnoredValueException - if this and beta are totally ignored

See Also:

Measurable.getDifference(Measurable, Measurable, Measurable, CanonicalFileDescriptor, Measurable.Difference)

getDifference

public Measurable.Difference getDifference(Measurable beta,
                                           Measurable blackout,
                                           Measurable ignore,
                                           CanonicalFileDescriptor cfd,
                                           Measurable.Difference old)
                                    throws IgnoredValueException

Description copied from interface: Measurable

For performance reasons, takes an optional (could be null) Measurable.Difference to replace the data from. Calling getDistance (alpha, beta, blackout, ignore) should have the same effect as getDistance (alpha.getDifference (beta, blackout, ignore)) (Except for if alpha is null... then it will use Distances.DefaultDifference

Specified by:

getDifference in interface Measurable

Parameters:

beta - the difference to get against

blackout - the measurable to count as bad

ignore - the measurable region to ignore

cfd - the media file descriptor

old - an old difference to copy into, if possible, like the array passed to list.toArray()

Returns:

the difference between this and beta

Throws:

IgnoredValueException - if everything is ignored

compose

public Composable compose(Composable partner)
                   throws java.lang.ClassCastException

Description copied from interface: Composable

Generate the composition of this object with its partner. If ordered, this is the object on the "left," whatever that means.

Specified by:

compose in interface Composable

Parameters:

partner -

Returns:

new Composable object from the this and the passed partner

Throws:

java.lang.ClassCastException

passes

public boolean passes(Filterable.Rule rule)

Description copied from interface: Filterable

Tests to see if the value passes the given rule.

Specified by:

passes in interface Filterable

Parameters:

rule - the rule to check this value against

Returns:

if this value is good according to the given rule