CLASS ndi.probe.image
ndi.probe.image - an imaging probe backed by an ndi.daq.system.image
ndi.probe.image is the imaging counterpart of the ndi.probe.timeseries /
ndi.probe.timeseries.mfdaq pair. It reads image frames from the
ndi.daq.system.image that acquired them and returns each frame's time
through the NDI epoch clock / syncgraph system, mirroring how
ndi.probe.timeseries returns sample times for ephys.
The key call is READFRAMES (alias READIMAGES):
[IMAGES, T, TIMEREF] = READFRAMES(PROBE, TIMEREF_OR_EPOCH, T0, T1)
How frame timestamps are returned (the imageseries timestamp question):
- The daq.reader (in NDR) supplies per-frame times via FRAMETIMES, in
the units of the epoch's clock (EPOCHCLOCK). For a movie that clock
is real (e.g. 'dev_local_time'); for a clockless stack it is
'no_time' and the times are NaN.
- READFRAMES maps the requested [T0,T1] from the caller's time
reference into the epoch's clock using session.syncgraph.time_convert,
selects the frames whose times fall in range, reads them, and
converts their times BACK into the caller's time reference. This is
exactly the path ndi.probe.timeseries/readtimeseries uses, so an
imageseries movie participates in the syncgraph like any timeseries.
ndi.time.timeseries interface:
ndi.probe.image implements ndi.time.timeseries, so it can be consumed
by generic timeseries code. READTIMESERIES returns image frames as the
data together with each frame's time, using the same syncgraph machinery
as READFRAMES. Because image frames are not (in general) regularly
sampled, SAMPLERATE returns -1 and the "sample <-> time" conversions
TIMES2SAMPLES / SAMPLES2TIMES map between frame indices and frame times
directly, via FRAMETIMES, rather than assuming a constant rate.
READTIMESERIES requires a real clock: on a clockless ('no_time') epoch,
where there is no time <-> frame mapping, it ERRORS and directs the
caller to READFRAMES with frame indices. (READFRAMES itself remains
dual-mode: time for a movie, frame indices for a clockless stack.)
See also: ndi.probe, ndi.probe.timeseries, ndi.time.timeseries,
ndi.daq.system.image, ndi.element.image
Superclasses
ndi.probe, ndi.element, ndi.ido, did.ido, ndi.epoch.epochset, ndi.documentservice, matlab.mixin.Heterogeneous, ndi.time.timeseries
Properties
| Property | Description |
|---|---|
| session | |
| name | |
| type | |
| reference | |
| underlying_element | |
| direct | |
| subject_id | |
| dependencies | |
| identifier |
Methods
| Method | Description |
|---|---|
| addepoch | add an epoch to the ndi.element |
| buildepochgraph | compute the epochgraph among epochs for an ndi.epoch.epochset object |
| buildepochtable | build the epoch table for an ndi.probe.* |
| buildmultipleepochtables | build epoch tables for multiple ndi.probe objects |
| cache2ginfo | CACHE2GINFO Make a regular GINFO from the smaller information stored in the cache |
| cached_epochgraph | return the cached epoch graph of an ndi.epoch.epochset object |
| cached_epochtable | return the cached epochtable of an ndi.epoch.epochset object |
| doc_unique_id | return the document unique reference for an ndi.element object |
| elementstring | Produce a human-readable element string |
| epoch2str | convert an epoch number or id to a string |
| epochclock | return the ndi.time.clocktype objects for an epoch |
| epochgraph | graph of the mapping and cost of converting time among epochs |
| epochid | Get the epoch identifier for a particular epoch |
| epochnodes | return all epoch nodes from an ndi.epoch.epochset object |
| epochprobemapmatch | does an epochprobemap record match our probe? |
| epochsetname | the name of the ndi.probe.* object, for EPOCHNODES |
| epochtable | Return an epoch table that relates the current object's epochs to underlying epochs |
| epochtableentry | return the entry of the EPOCHTABLE that corresponds to an EPOCHID |
| eq | are 2 ndi.probe objects equal? |
| framesize | [Y X C Z T] extent of the probe's image data in an epoch |
| getcache | return the NDI_CACHE and key for ndi.element |
| getchanneldevinfo | GETCHANNELDEVINFO = Get the device, channeltype, and channellist for a given epoch for ndi.probe.* |
| getepocharray | Return an array of ndi.epoch objects that relates the current object's epochs to underlying epochs |
| ginfo2cache | GINFO2CACHE Make a smaller version of the GINFO for storage in the cache |
| id | return the document unique identifier for an ndi.element object |
| image | create a new ndi.probe.image object |
| imagemetadata | standardized image-acquisition metadata for an epoch |
| issyncgraphroot | should this object be a root in an ndi.time.syncgraph epoch graph? |
| isvalid | is a unique ID number valid? |
| linetimes | acquisition time of each line (row) of the selected frames |
| load_all_element_docs | load all of the ndi.element objects from an session database |
| load_element_doc | load a element doc from the session database |
| loadaddedepochs | load the added epochs from an ndi.element |
| matchedepochtable | compare a hash number from an epochtable to the current version |
| newdocument | return a new database document of type ndi.document based on a element |
| numepochs | Number of epochs of ndi.epoch.epochset |
| numframes | number of frames available to this probe in an epoch |
| pixeltimes | acquisition time of every pixel of the selected frames |
| probestring | Produce a human-readable probe string |
| readframes | read image frames with frame times via the epoch clock system |
| readframesepoch | read image frames from a single epoch |
| readimages | alias of READFRAMES |
| readtimeseries | read image frames as a time series |
| readtimeseriesepoch | read image frames from one epoch as a time series |
| resetepochtable | clear an ndi.epoch.epochset epochtable in memory and force it to be re-read from disk |
| samplerate | image frames are not regularly sampled; returns -1 |
| samples2times | map frame indices to epoch-clock times |
| searchquery | return a search query for an ndi.document based on this element |
| t0_t1 | |
| times2samples | map epoch-clock times to frame indices |
| underlyingepochnodes | find all the underlying epochnodes of a given epochnode |
| unique_id | Generate a unique ID number for DID databases (Static method) |
Methods help
addepoch - add an epoch to the ndi.element
[NDI_ELEMENT_OBJ, EPOCHDOC] = ADDEPOCH(NDI_ELEMENT_OBJ, EPOCHID, EPOCHCLOCK, T0_T1, [ADD_TO_DB], [EPOCHIDS])
Registers the data for an epoch with the NDI_ELEMENT_OBJ.
Inputs:
NDI_ELEMENT_OBJ: The ndi.element object to modify
EPOCHID: The name of the epoch to add; should match the name of an epoch from the probe
EPOCHCLOCK: The epoch clock; must be a single clock type that matches one of the clock types
of the probe
T0_T1: The starting time and ending time of the existence of information about the ELEMENT on
the probe, in units of the epock clock
ADD_TO_DB: 0/1 Should we actually add the epoch document to the database? Default 0.
EPOCHIDS: The epoch ids of the original epochs (used in conjunction with a oneepoch document).
Help for ndi.probe.image/addepoch is inherited from superclass ndi.element
buildepochgraph - compute the epochgraph among epochs for an ndi.epoch.epochset object
[COST,MAPPING] = BUILDEPOCHGRAPH(NDI_EPOCHSET_OBJ)
Compute the cost and the mapping among epochs in the EPOCHTABLE for an ndi.epoch.epochset object
COST is an MxM matrix where M is the number of EPOCHNODES.
For example, if there is one epoch with clock types 'dev_local_time' and 'utc', then M is 2.
Each entry COST(i,j) indicates whether there is a mapping between (epoch, clocktype) i to j.
The cost of each transformation is normally 1 operation.
MAPPING is the ndi.time.timemapping object that describes the mapping.
In the abstract class, the following NDI_CLOCKTYPEs, if they exist, are linked across epochs with
a cost of 1 and a linear mapping rule with shift 1 and offset 0:
'utc' -> 'utc'
'utc' -> 'approx_utc'
'exp_global_time' -> 'exp_global_time'
'exp_global_time' -> 'approx_exp_global_time'
'dev_global_time' -> 'dev_global_time'
'dev_global_time' -> 'approx_dev_global_time'
See also: ndi.time.clocktype, ndi.time.clocktype/ndi.time.clocktype, ndi.time.timemapping, ndi.time.timemapping/ndi.time.timemapping,
ndi.probe.image/EPOCHNODES
Help for ndi.probe.image/buildepochgraph is inherited from superclass ndi.epoch.epochset
buildepochtable - build the epoch table for an ndi.probe.*
ET = BUILDEPOCHTABLE(NDI_PROBE_OBJ)
ET is a structure array with the following fields:
Fieldname: | Description
------------------------------------------------------------------------
'epoch_number' | The number of the epoch (may change)
'epoch_id' | The epoch ID code (will never change once established)
| This uniquely specifies the epoch.
'epoch_session_id' | The ID of the session
'epochprobemap' | The epochprobemap object from each epoch
'epoch_clock' | A cell array of ndi.time.clocktype objects that describe the type of clocks available
't0_t1' | A cell array of ordered pairs [t0 t1] that indicates, for each ndi.time.clocktype, the start and stop
| time of this epoch. The time units of t0_t1{i} match epoch_clock{i}.
'underlying_epochs' | A structure array of the ndi.epoch.epochset objects that comprise these epochs.
| It contains fields 'underlying', 'epoch_number', and 'epoch_id'
Help for ndi.probe.image/buildepochtable is inherited from superclass ndi.probe
buildmultipleepochtables - build epoch tables for multiple ndi.probe objects
ET = BUILDMULTIPLEEPOCHTABLES(PROBECELLARRAY)
ET is a cell array of structures, where each structure is an epoch table for the
corresponding ndi.probe object in the input cell array PROBECELLARRAY.
This function is more efficient than calling BUILDEPOCHTABLE for each probe individually
because it minimizes redundant operations by using an index and checking the session cache.
Help for ndi.probe.image.buildmultipleepochtables is inherited from superclass ndi.probe
cache2ginfo - CACHE2GINFO Make a regular GINFO from the smaller information stored in the cache
GINFO_BIG = GINFO2CACHE(GINFO_SMALL)
Help for ndi.probe.image.cache2ginfo is inherited from superclass ndi.epoch.epochset
cached_epochgraph - return the cached epoch graph of an ndi.epoch.epochset object
[COST,MAPPING] = CACHED_EPOCHGRAPH(NDI_EPOCHSET_OBJ)
Return the cached version of the epoch graph, if it exists and is up-to-date
(that is, the hash number from the EPOCHTABLE of NDI_EPOCHSET_OBJ
has not changed). If there is no cached version, or if it is not up-to-date,
COST and MAPPING will be empty. If the cached epochgraph is present and not up-to-date,
it is deleted.
See also: NDI_EPOCHSET_OBJ/EPOCHGRAPH, NDI_EPOCHSET_OBJ/BUILDEPOCHGRAPH
Help for ndi.probe.image/cached_epochgraph is inherited from superclass ndi.epoch.epochset
cached_epochtable - return the cached epochtable of an ndi.epoch.epochset object
[ET, HASHVALUE] = CACHED_EPOCHTABLE(NDI_EPOCHSET_OBJ)
Return the cached version of the epochtable, if it exists, along with its HASHVALUE
(a hash number generated from the table). If there is no cached version,
ET and HASHVALUE will be empty.
Help for ndi.probe.image/cached_epochtable is inherited from superclass ndi.epoch.epochset
doc_unique_id - return the document unique reference for an ndi.element object
UNIQUE_REF = DOC_UNIQUE_ID(NDI_ELEMENT_OBJ)
Returns the document unique reference for NDI_ELEMENT_OBJ. If there is no associated
document for the element, then empty is returned.
Help for ndi.probe.image/doc_unique_id is inherited from superclass ndi.element
elementstring - Produce a human-readable element string
ELEMENTSTR = ELEMENTSTRING(NDI_ELEMENT_OBJ)
Returns the name as a human-readable string.
For ndi.element objects, this is the string 'element: ' followed by its name
This string is for display only. It contains a '|', which is not a legal
filename character on Windows, so it must not be used to build file or
folder names; use ndi.fun.file.elementDirectoryName (or
ndi.fun.file.elementDirectory) for that.
See also: ndi.fun.file.elementDirectoryName, ndi.fun.file.elementDirectory
Help for ndi.probe.image/elementstring is inherited from superclass ndi.element
epoch2str - convert an epoch number or id to a string
S = EPOCH2STR(NDI_EPOCHSET_OBJ, NUMBER)
Returns the epoch NUMBER in the form of a string. If it is a simple
integer, then INT2STR is used to produce a string. If it is an epoch
identifier string, then it is returned.
Help for ndi.probe.image/epoch2str is inherited from superclass ndi.epoch.epochset
epochclock - return the ndi.time.clocktype objects for an epoch
EC = EPOCHCLOCK(NDI_PROBE_OBJ, EPOCH_NUMBER)
Return the clock types available for this epoch.
The ndi.probe class always returns the clock type(s) of the device it is based on
Help for ndi.probe.image/epochclock is inherited from superclass ndi.probe
epochgraph - graph of the mapping and cost of converting time among epochs
[COST, MAPPING] = EPOCHGRAPH(NDI_EPOCHSET_OBJ)
Compute the cost and the mapping among epochs in the EPOCHTABLE for an ndi.epoch.epochset object
COST is an MxM matrix where M is the number of ordered pairs of (epochs, clocktypes).
For example, if there is one epoch with clock types 'dev_local_time' and 'utc', then M is 2.
Each entry COST(i,j) indicates whether there is a mapping between (epoch, clocktype) i to j.
The cost of each transformation is normally 1 operation.
MAPPING is the ndi.time.timemapping object that describes the mapping.
Help for ndi.probe.image/epochgraph is inherited from superclass ndi.epoch.epochset
epochid - Get the epoch identifier for a particular epoch
ID = EPOCHID (NDI_EPOCHSET_OBJ, EPOCH_NUMBER)
Returns the epoch identifier string for the epoch EPOCH_NUMBER.
If it doesn't exist, it should be created. EPOCH_NUMBER can be
a number of an EPOCH ID string.
The abstract class just queries the EPOCHTABLE.
Most classes that manage epochs themselves (ndi.file.navigator,
ndi.daq.system) will override this method.
Help for ndi.probe.image/epochid is inherited from superclass ndi.epoch.epochset
epochnodes - return all epoch nodes from an ndi.epoch.epochset object
[NODES,UNDERLYINGNODES] = EPOCHNODES(NDI_EPOCHSET_OBJ)
Return all EPOCHNODES for an ndi.epoch.epochset. EPOCHNODES consist of the
following fields:
Fieldname: | Description
------------------------------------------------------------------------
'epoch_id' | The epoch ID code (will never change once established, though it may be deleted.)
| This epoch ID uniquely specifies the epoch within the session.
'epoch_session_id' | The ID of the session that contains the epoch
'epochprobemap' | Any contents information for each epoch, usually of type ndi.epoch.epochprobemap or empty.
'epoch_clock' | A SINGLE ndi.time.clocktype entry that describes the clock type of this node.
't0_t1' | The times [t0 t1] of the beginning and end of the epoch in units of 'epoch_clock'
'underlying_epochs' | A structure array of the ndi.epoch.epochset objects that comprise these epochs.
| It contains fields 'underlying', 'epoch_id', and 'epochprobemap'
'objectname' | A string containing the 'name' field of NDI_EPOCHSET_OBJ, if it exists. If there is no
| 'name' field, then 'unknown' is used.
'objectclass' | The object class name of the NDI_EPOCHSET_OBJ.
EPOCHNODES are related to EPOCHTABLE entries, except
a) only 1 ndi.time.clocktype is permitted per epoch node. If an entry in epoch table contains
multiple ndi.time.clocktype entries, then each one will have its own epoch node. This aids
in the construction of the EPOCHGRAPH that helps the system map time from one epoch to another.
b) EPOCHNODES contain identifying information (objectname and objectclass) to help
in identifying the epoch nodes across ndi.epoch.epochset objects.
UNDERLYINGNODES are nodes that are directly linked to this ndi.epoch.epochset's node via 'underlying' epochs.
Help for ndi.probe.image/epochnodes is inherited from superclass ndi.epoch.epochset
epochprobemapmatch - does an epochprobemap record match our probe?
B = EPOCHPROBEMAPMATCH(NDI_PROBE_OBJ, EPOCHPROBEMAP)
Returns 1 if the ndi.epoch.epochprobemap object EPOCHPROBEMAP is a match for
the NDI_PROBE_OBJ probe and 0 otherwise.
Help for ndi.probe.image/epochprobemapmatch is inherited from superclass ndi.probe
epochsetname - the name of the ndi.probe. object, for EPOCHNODES*
NAME = EPOCHSETNAME(NDI_PROBE_OBJ)
Returns the object name that is used when creating epoch nodes.
For ndi.probe objects, this is the string 'probe: ' followed by
PROBESTRING(NDI_PROBE_OBJ).
Help for ndi.probe.image/epochsetname is inherited from superclass ndi.probe
epochtable - Return an epoch table that relates the current object's epochs to underlying epochs
[ET,HASHVALUE] = EPOCHTABLE(NDI_EPOCHSET_OBJ)
ET is a structure array with the following fields:
Fieldname: | Description
------------------------------------------------------------------------
'epoch_number' | The number of the epoch. The number may change as epochs are added and subtracted.
'epoch_id' | The epoch ID code (will never change once established, though it may be deleted.)
| This epoch ID uniquely specifies the epoch.
'epoch_session_id' | The session ID that contains this epoch
'epochprobemap' | Any contents information for each epoch, usually of type ndi.epoch.epochprobemap or empty.
'epoch_clock' | A cell array of ndi.time.clocktype objects that describe the type of clocks available
't0_t1' | A cell array of ordered pairs [t0 t1] that indicates, for each ndi.time.clocktype, the start and stop
| time of this epoch. The time units of t0_t1{i} match epoch_clock{i}.
'underlying_epochs' | A structure array of the ndi.epoch.epochset objects that comprise these epochs.
| It contains fields 'underlying', 'epoch_number', 'epoch_id', and 'epochprobemap'
HASHVALUE is the hashed value of the epochtable. One can check to see if the epochtable
has changed with ndi.epoch.epochset/MATCHEDEPOCHTABLE.
After it is read from disk once, the ET is stored in memory and is not re-read from disk
unless the user calls ndi.epoch.epochset/RESETEPOCHTABLE.
Help for ndi.probe.image/epochtable is inherited from superclass ndi.epoch.epochset
epochtableentry - return the entry of the EPOCHTABLE that corresponds to an EPOCHID
ET_ENTRY = EPOCHTABLEENTRY(NDI_EPOCHSET_OBJ, EPOCH_NUMBER_OR_ID)
Returns the EPOCHTABLE entry associated with the ndi.epoch.epochset object
that corresponds to EPOCH_NUMBER_OR_ID, which can be the number of the
epoch or the EPOCHID of the epoch.
Help for ndi.probe.image/epochtableentry is inherited from superclass ndi.epoch.epochset
eq - are 2 ndi.probe objects equal?
Returns 1 if the objects share an object class, session, and probe string.
Help for ndi.probe.image/eq is inherited from superclass ndi.probe
framesize - [Y X C Z T] extent of the probe's image data in an epoch
getcache - return the NDI_CACHE and key for ndi.element
[CACHE,KEY] = GETCACHE(NDI_ELEMENT_OBJ)
Returns the CACHE and KEY for the ndi.element object.
The CACHE is returned from the associated session.
The KEY is the probe's ELEMENTSTRING plus the TYPE of the ELEMENT.
See also: ndi.file.navigator
Help for ndi.probe.image/getcache is inherited from superclass ndi.element
getchanneldevinfo - GETCHANNELDEVINFO = Get the device, channeltype, and channellist for a given epoch for ndi.probe.*
[DEV, DEVNAME, DEVEPOCH, CHANNELTYPE, CHANNELLIST] = GETCHANNELDEVINFO(NDI_PROBE_OBJ, EPOCH_NUMBER_OR_ID)
Given an ndi.probe.* object and an EPOCH number, this function returns the corresponding channel and device info.
Suppose there are C channels corresponding to a probe. Then the outputs are
DEV is a 1xC cell array of ndi.daq.system objects for each channel
DEVNAME is a 1xC cell array of the names of each device in DEV
DEVEPOCH is a 1xC array with the epoch id of the probe's EPOCH on each device
CHANNELTYPE is a cell array of the type of each channel
CHANNELLIST is the channel number of each channel.
Help for ndi.probe.image/getchanneldevinfo is inherited from superclass ndi.probe
getepocharray - Return an array of ndi.epoch objects that relates the current object's epochs to underlying epochs
EPOCHOBJECTARRAY = GETEPOCHARRAY(NDI_EPOCHSET_OBJ)
Produce an array of ndi.epoch objects from the epoch table of this
ndi.epoch.epochset object (NDI_EPOCHSET_OBJ).
Help for ndi.probe.image/getepocharray is inherited from superclass ndi.epoch.epochset
ginfo2cache - GINFO2CACHE Make a smaller version of the GINFO for storage in the cache
GINFO_SMALL = GINFO2CACHE(GINFO)
Help for ndi.probe.image.ginfo2cache is inherited from superclass ndi.epoch.epochset
id - return the document unique identifier for an ndi.element object
UNIQUE_REF = ID(NDI_ELEMENT_OBJ)
Returns the document unique reference for NDI_ELEMENT_OBJ. If there is no associated
document for the element, then an error is returned.
Help for ndi.probe.image/id is inherited from superclass ndi.element
image - create a new ndi.probe.image object
OBJ = ndi.probe.image(SESSION, NAME, REFERENCE, TYPE)
Documentation for ndi.probe.image
doc ndi.probe.image
imagemetadata - standardized image-acquisition metadata for an epoch
M = IMAGEMETADATA(NDI_PROBE_IMAGE_OBJ, EPOCH)
Returns the standardized image-acquisition metadata struct for
EPOCH from the backing ndi.daq.system.image: raster line/frame
timing, geometry, and scan direction, with all time fields in
SECONDS. See ndi.daq.reader.image/metadata for the field list.
Fields that are unknown (e.g. for a non-raster stack) are NaN, and
M.israster is false.
See also: ndi.daq.reader.image/metadata, linetimes, pixeltimes
issyncgraphroot - should this object be a root in an ndi.time.syncgraph epoch graph?
B = ISSYNCGRAPHROOT(NDI_EPOCHSET_OBJ)
This function tells an ndi.time.syncgraph object whether it should continue
adding the 'underlying' epochs to the graph, or whether it should stop at this level.
For ndi.epoch.epochset and ndi.probe.* this returns 0 so that the underlying ndi.daq.system epochs are added.
Help for ndi.probe.image/issyncgraphroot is inherited from superclass ndi.probe
isvalid - is a unique ID number valid?
B = isvalid(ID)
Returns true if ID matches the structure of a did.ido identifier and
false otherwise. A valid ID must have 16 hexadecimal digits in
0-9 or a-f, an underscore, and then 16 more hexadecimal digits.
Help for ndi.probe.image.isvalid is inherited from superclass did.ido
linetimes - acquisition time of each line (row) of the selected frames
TL = LINETIMES(NDI_PROBE_IMAGE_OBJ, TIMEREF_OR_EPOCH, T0, T1)
A raster scan builds a frame line by line, so at slow frame rates
the top of a frame is acquired well before the bottom. LINETIMES
returns the time each line (row) was scanned, so you can ask which
rows had been acquired at a given moment.
The frames are selected exactly as by READFRAMES with the same
arguments (TIMEREF_OR_EPOCH is an ndi.time.timereference, then
T0,T1 are times in that reference; or an epoch number/id, then
T0,T1 are times in the epoch's clock). TL is returned in the SAME
time units as those frames.
TL is [Lines_per_frame x Nframes]: TL(r,k) is the time the r-th
line of the k-th selected frame was scanned, computed as
TL(r,k) = frametime(k) + (r-1) * line_period
so TL(1,k) equals that frame's time and each column steps down by
line_period. (Scan direction does not change a line's start time,
so BIDIRECTIONAL does not affect LINETIMES; it only matters for
PIXELTIMES.)
Requires a raster epoch with a known line_period (see
IMAGEMETADATA); otherwise an error is raised. Clockless ('no_time')
epochs also error, as they have no frame times. This assumes
FRAMETIMES reports each frame's START time.
Only a single epoch per call is supported; a TIMEREF interval that
spans multiple epochs raises an error.
See also: pixeltimes, imagemetadata, ndi.probe.image/readframes
load_all_element_docs - load all of the ndi.element objects from an session database
ELEMENT_DOCS = LOAD_ALL_ELEMENT_DOCS(NDI_ELEMENT_OBJ)
Loads the ndi.document that is based on the ndi.element object and any associated
epoch documents.
Help for ndi.probe.image/load_all_element_docs is inherited from superclass ndi.element
load_element_doc - load a element doc from the session database
ELEMENT_DOC = LOAD_ELEMENT_DOC(NDI_ELEMENT_OBJ)
Load an ndi.document that is based on the ndi.element object.
Returns empty if there is no such document.
Help for ndi.probe.image/load_element_doc is inherited from superclass ndi.element
loadaddedepochs - load the added epochs from an ndi.element
[ET_ADDED, EPOCHDOCS] = LOADADDEDEOPCHS(NDI_ELEMENT_OBJ)
Load the EPOCHTABLE that consists of added/registered epochs that provide information
about the ndi.element.
Help for ndi.probe.image/loadaddedepochs is inherited from superclass ndi.element
matchedepochtable - compare a hash number from an epochtable to the current version
B = MATCHEDEPOCHTABLE(NDI_EPOCHSET_OBJ, HASHVALUE)
Returns 1 if the current hashed value of the cached epochtable is identical to HASHVALUE.
Otherwise, it returns 0.
Help for ndi.probe.image/matchedepochtable is inherited from superclass ndi.epoch.epochset
newdocument - return a new database document of type ndi.document based on a element
NDI_DOCUMENT_OBJ = NEWDOCUMENT(NDI_ELEMENT_OBJ)
Fill out the fields of an NDI_DOCUMENT_OBJ of type 'element'
with the corresponding 'name' and 'type' fields of the element NDI_ELEMENT_OBJ and the
'name', 'type', and 'reference' fields of its underlying NDI_PROBE_OBJ.
If EPOCHID is provided, then an EPOCHID field is filled out as well
in accordance to 'epochid'.
When the document is created, it is automatically added to the session.
Help for ndi.probe.image/newdocument is inherited from superclass ndi.element
numepochs - Number of epochs of ndi.epoch.epochset
N = NUMEPOCHS(NDI_EPOCHSET_OBJ)
Returns the number of epochs in the ndi.epoch.epochset object NDI_EPOCHSET_OBJ.
See also: EPOCHTABLE
Help for ndi.probe.image/numepochs is inherited from superclass ndi.epoch.epochset
numframes - number of frames available to this probe in an epoch
N = NUMFRAMES(NDI_PROBE_IMAGE_OBJ, EPOCH)
pixeltimes - acquisition time of every pixel of the selected frames
TP = PIXELTIMES(NDI_PROBE_IMAGE_OBJ, TIMEREF_OR_EPOCH, T0, T1)
Like LINETIMES, but resolved to the individual pixel: the time each
pixel was sampled within a raster scan. Frame selection and time
units follow READFRAMES with the same arguments (see LINETIMES).
TP(r,c,1,1,k) = frametime(k) + (r-1)*line_period + (c-1)*dwell_time
(For a BIDIRECTIONAL scan, alternate lines are traversed in reverse,
so the within-line dwell offset is mirrored on those rows.)
COMPACT SHAPE (and why): TP is [Y X 1 1 Nframes]. A pixel's sample
time depends on its row (line), its column (pixel-in-line) and the
frame, but NOT on the color channel C (all detectors sample a given
beam position simultaneously) and, in v1, not on the plane Z.
Keeping C and Z as SINGLETON dimensions lets TP BROADCAST
elementwise against the full data array [Y X C Z Nframes] via
implicit expansion, at a fraction of the memory: times are double
(8 bytes) versus 2 bytes for typical uint16 pixels, so a full-size
time map would be ~4x the size of the image data itself.
Example - which pixels had been scanned at an event time:
[data,t,tr] = p.readframes(myref, 0, 100);
tp = p.pixeltimes(myref, 0, 100); % [Y X 1 1 nframes]
mask = tp >= eventTime; % [Y X 1 1 nframes]
seen = data .* cast(mask, class(data)); % broadcasts over C,Z
Example - build the FULL [Y X C Z nframes] matrix if you must:
sz = size(data);
tpfull = repmat(tp, [1 1 sz(3) sz(4) 1]); % replicate across C,Z
(The compact form is the default precisely so you rarely need this.)
Requires a raster epoch with known line_period AND dwell_time;
otherwise an error is raised (use LINETIMES for line-level timing
when dwell_time is unavailable). Assumes FRAMETIMES reports each
frame's START time. Single epoch per call.
See also: linetimes, imagemetadata, ndi.probe.image/readframes
probestring - Produce a human-readable probe string
PROBESTR = PROBESTRING(NDI_PROBE_OBJ)
Returns the name and reference of a probe as a human-readable string.
This is simply PROBESTR = [NDI_PROBE_OBJ.name ' _ ' in2str(NDI_PROBE_OBJ.reference)]
Help for ndi.probe.image/probestring is inherited from superclass ndi.probe
readframes - read image frames with frame times via the epoch clock system
[IMAGES, T, TIMEREF] = READFRAMES(NDI_PROBE_IMAGE_OBJ, TIMEREF_OR_EPOCH, T0, T1)
[IMAGES, T, TIMEREF] = READFRAMES(..., 'SelectC', C, 'SelectZ', Z)
Reads image frames from the backing ndi.daq.system.image. If
TIMEREF_OR_EPOCH is an ndi.time.timereference, T0,T1 are times in
that reference; the request is mapped into the epoch's own clock
via the syncgraph, the in-range frames are read, and their times
are converted back into TIMEREF's units. If TIMEREF_OR_EPOCH is an
epoch number/id, the read is performed directly in that epoch's
clock (T0,T1 are times for a movie, or frame indices for a
clockless epoch).
The 'SelectC' / 'SelectZ' options subset the returned channel /
plane axes (default [] = all).
readframesepoch - read image frames from a single epoch
[IMAGES, T, TIMEREF_OUT] = READFRAMESEPOCH(NDI_PROBE_IMAGE_OBJ, EPOCH, T0, T1)
[IMAGES, T, TIMEREF_OUT] = READFRAMESEPOCH(..., 'SelectC', C, 'SelectZ', Z)
EPOCH is the epoch number or id. For a movie, returns the frames
whose times (in the epoch's clock) fall within [T0,T1] and T is
those times relative to the start of the epoch. For a clockless
('no_time') epoch, T0,T1 are inclusive frame-index bounds and T
is the frame indices. TIMEREF_OUT describes the epoch.
The 'SelectC' / 'SelectZ' options subset the returned channel /
plane axes (default [] = all).
readimages - alias of READFRAMES
See also: ndi.probe.image/readframes
readtimeseries - read image frames as a time series
[DATA, T, TIMEREF] = READTIMESERIES(NDI_PROBE_IMAGE_OBJ, TIMEREF_OR_EPOCH, T0, T1)
Implements the ndi.time.timeseries interface for an imaging probe.
Returns image frames as DATA (a [Y X C Z nframes] array) together
with the time T of each frame and the TIMEREF describing T.
TIMEREF_OR_EPOCH is either an ndi.time.timereference (then T0,T1
are times in that reference and the request is mapped through the
syncgraph) or an epoch number/id (then T0,T1 are times in the
epoch's own clock). Only frames whose times fall within [T0,T1]
are returned.
Unlike READFRAMES, this method requires a real clock: reading a
clockless ('no_time') epoch raises an error (there is no
time <-> frame mapping). Use READFRAMES with frame indices for
clockless epochs. See READTIMESERIESEPOCH.
readtimeseriesepoch - read image frames from one epoch as a time series
[DATA, T, TIMEREF] = READTIMESERIESEPOCH(NDI_PROBE_IMAGE_OBJ, EPOCH, T0, T1)
[DATA, T, TIMEREF] = READTIMESERIESEPOCH(..., 'SelectC', C, 'SelectZ', Z)
Returns the frames of EPOCH whose times (in the epoch's clock) fall
within [T0,T1], as DATA, with the frame times T and the epoch
TIMEREF. EPOCH is an epoch number or id. The 'SelectC' / 'SelectZ'
options subset the returned channel / plane axes (default [] = all).
If EPOCH is clockless (its clock is 'no_time') this method errors,
because a time series has no meaning without a clock; use
ndi.probe.image/readframes with frame indices instead.
resetepochtable - clear an ndi.epoch.epochset epochtable in memory and force it to be re-read from disk
NDI_EPOCHSET_OBJ = RESETEPOCHTABLE(NDI_EPOCHSET_OBJ)
This function clears the internal cached memory of the epochtable, forcing it to be re-read from
disk at the next request.
See also: ndi.probe.image/EPOCHTABLE
Help for ndi.probe.image/resetepochtable is inherited from superclass ndi.epoch.epochset
samplerate - image frames are not regularly sampled; returns -1
SR = SAMPLERATE(NDI_PROBE_IMAGE_OBJ, EPOCH)
Image frames may be irregularly timed (e.g. PrairieView per-frame
timestamps, dropped frames), so no single sample rate applies and
-1 is returned, per the ndi.time.timeseries convention. Use
FRAMETIMES / TIMES2SAMPLES / SAMPLES2TIMES for the frame<->time
mapping.
samples2times - map frame indices to epoch-clock times
TIMES = SAMPLES2TIMES(NDI_PROBE_IMAGE_OBJ, EPOCH, SAMPLES)
For image data a "sample" is a frame. Returns the time (from
FRAMETIMES, in the epoch's clock units) of each frame index in
SAMPLES; out-of-range indices return NaN. Errors on a clockless
('no_time') epoch.
searchquery - return a search query for an ndi.document based on this element
SQ = SEARCHQUERY(NDI_ELEMENT_OBJ, [EPOCHID])
Returns a search query for the fields of an NDI_DOCUMENT_OBJ of type 'element'
with the corresponding 'name' and 'type' fields of the element NDI_ELEMENT_OBJ.
Help for ndi.probe.image/searchquery is inherited from superclass ndi.element
t0_t1 - **
T0_T1 - return the t0_t1 (beginning and end) epoch times for an epoch
T0T1 = T0_T1(NDI_EPOCHSET_OBJ, EPOCH_NUMBER)
Return the beginning (t0) and end (t1) times of the epoch EPOCH_NUMBER
in the same units as the ndi.time.clocktype objects returned by EPOCHCLOCK.
The abstract class always returns {[NaN NaN]}.
See also: ndi.time.clocktype, EPOCHCLOCK
TODO: this must be a bug, it's just self-referential
Help for ndi.probe.image/t0_t1 is inherited from superclass ndi.element
times2samples - map epoch-clock times to frame indices
SAMPLES = TIMES2SAMPLES(NDI_PROBE_IMAGE_OBJ, EPOCH, TIMES)
For image data a "sample" is a frame. Returns, for each requested
time in TIMES (in the epoch's clock units), the index of the
nearest frame, found from FRAMETIMES. +Inf maps to the last frame
and -Inf to the first. Errors on a clockless ('no_time') epoch.
underlyingepochnodes - find all the underlying epochnodes of a given epochnode
[UNODES, COST, MAPPING] = UNDERLYINGEPOCHNODES(NDI_EPOCHSET_OBJ, EPOCHNODE)
Traverse the underlying nodes of a given EPOCHNODE until we get to the roots
(an ndi.epoch.epochset object with ISSYNGRAPHROOT that returns 1).
Note that the EPOCHNODE itself is returned as the first 'underlying' node.
See also: ISSYNCGRAPHROOT
Help for ndi.probe.image/underlyingepochnodes is inherited from superclass ndi.epoch.epochset
unique_id - Generate a unique ID number for DID databases (Static method)
ID = DID.IDO.UNIQUE_ID()
Generates a unique ID character array based on the current time and a random
number. It is a hexadecimal representation of the serial date number in
UTC Leap Seconds time. The serial date number is the number of days since January 0, 0000 at 0:00:00.
The integer portion of the date is the whole number of days and the fractional part of the date number
is the fraction of days.
ID = [NUM2HEX(SERIAL_DATE_NUMBER) '_' NUM2HEX(RAND)]
See also: NUM2HEX, NOW, RAND
Help for ndi.probe.image.unique_id is inherited from superclass did.ido