tracee 0.0.4__py3-none-any.whl

notebook/sample/generate_knn-graph.py

@@ -0,0 +1,29 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+from argparse import ArgumentParser as ap
+import numpy as np
+import tracee
+
+
+if __name__ == '__main__':
+  parser = ap(description='dump k-NN graph')
+
+  parser.add_argument(
+    'input', type=str, help='input file name')
+  parser.add_argument(
+    'k', type=int, help='the number of neighbor')
+  parser.add_argument(
+    'output', type=str, help='output file name')
+
+  args = parser.parse_args()
+
+  data = np.loadtxt(args.input)
+  edge = tracee.generate_edge(data, args.k, 200)
+
+  v0 = data[edge[:,0],:]
+  v1 = data[edge[:,1],:]
+  els = np.hstack((v0,v1))
+
+  print(els)
+  fmt = ('%.3f','%.3f','%d','%.3f','%.3f','%d')
+  np.savetxt(args.output, els, fmt=fmt)

notebook/sample/generate_mock_data.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+from argparse import ArgumentParser as ap
+from time import time
+import numpy as np
+
+header = '''Generated Mock Data
+
+Parameters:
+  number of objects: {n_object:d}
+  number of frames: {n_frame:d}
+  number of distractors: {n_distractor:d}
+  object velocity: {velocity:.1f}
+  object drop rate: {drop:.1f}
+  field of view size: {size:d}
+  random seed: {seed:d}
+Columns:
+  1st column: x position
+  2nd column: y position
+  3rd column: timestamp
+'''
+savefmt = ('%12.6f','%12.6f','%4d')
+
+
+if __name__ == '__main__':
+  parser = ap(description='generate mock data')
+
+  parser.add_argument(
+    'n_object', type=int,
+    help='the number of moving objects')
+  parser.add_argument(
+    'n_frame', type=int,
+    help='the number of frames')
+  parser.add_argument(
+    'n_distractor',  type=int,
+    help='the number of distractors')
+  parser.add_argument(
+    '-v', '--velocity', type=int, default=5.0,
+    help='the velocity of moving objects')
+  parser.add_argument(
+    '-s', '--scatter', type=float, default=0.2,
+    help='scatter in the positions')
+  parser.add_argument(
+    '--drop', type=float, default=0.0,
+    help='drop rate between [0,1]')
+  parser.add_argument(
+    '--seed', type=int, default=None,
+    help='the seed of random generator')
+  parser.add_argument(
+    '--size', type=int, default=512,
+    help='the size of the field of view')
+  parser.add_argument(
+    '--margin', type=int, default=64,
+    help='margins of the field of view')
+  parser.add_argument(
+    '-q', '--quiet', action='store_true',
+    help='disable plot')
+
+  args = parser.parse_args()
+  shape = (args.n_object,1)
+  if args.seed is None:
+    args.seed = round(time())%65536
+  np.random.seed(args.seed)
+
+  L = args.size-2*args.margin
+  x0 = L*np.random.uniform(size=shape)+args.margin
+  y0 = L*np.random.uniform(size=shape)+args.margin
+  vx = args.velocity*np.random.normal(size=shape)
+  vy = args.velocity*np.random.normal(size=shape)
+  t = np.atleast_2d(np.arange(args.n_frame))
+
+  x,y = (x0+vx*t).flatten(),(y0+vy*t).flatten()
+  tt = np.tile(t,args.n_object).flatten()
+  x += np.random.normal(0, args.scatter, size=x.shape)
+  y += np.random.normal(0, args.scatter, size=y.shape)
+
+  position = np.vstack((x,y,tt)).T
+  ## remove vertices outside of the field of view
+  flag = (x>0) & (x<args.size) & (y>0) & (y<args.size)
+  position = position[flag,:]
+  ## remove random objects
+  flag = np.random.uniform(size=position.shape[0])>args.drop
+  position = position[flag,:]
+
+  ## add distractors
+  if args.n_distractor>0:
+    dx = np.random.uniform(args.size, size=args.n_distractor)
+    dy = np.random.uniform(args.size, size=args.n_distractor)
+    dt = np.random.uniform(args.n_frame, size=args.n_distractor)
+    dist = np.vstack((dx,dy,dt)).T
+    position = np.concatenate((position,dist))
+
+  ## sort position list chronologically
+  idx = np.argsort(position[:,2])
+  position = position[idx,:]
+
+  filename = 'mockdata_N{:03d}F{:03d}D{:03d}d{:02d}_{:04x}.txt'.format(
+    args.n_object,args.n_frame,args.n_distractor,
+    round(args.drop*100),args.seed)
+  np.savetxt(filename, position, fmt=savefmt,
+             header=header.format(**args.__dict__))
+
+  if args.quiet is False:
+    import matplotlib.pyplot as plt
+    fig = plt.figure(figsize=(10,10))
+    ax = fig.add_subplot()
+    ax.scatter(position[:,0],position[:,1],marker='+')
+    fig.tight_layout()
+    plt.show()

notebook/sample/generate_tracklet.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+from argparse import ArgumentParser as ap
+import numpy as np
+import tracee
+
+
+if __name__ == '__main__':
+  parser = ap(description='dump tracklet')
+
+  parser.add_argument(
+    'input', type=str, help='input file name')
+  parser.add_argument(
+    'k', type=int, help='the number of neighbor')
+  parser.add_argument(
+    'output', type=str, help='output file name')
+  parser.add_argument(
+    '-L', '--limit', type=int, default=10,
+    help='shortest tracklet to be extracted')
+
+  args = parser.parse_args()
+
+  data = np.loadtxt(args.input)
+  param = tracee.default_parameters()
+  param.limit = args.limit
+  tracklet = tracee.extract(data, n_neighbor=args.k, param=param)
+
+  v0 = np.array([t.tail for t in tracklet])
+  v1 = np.array([t.head for t in tracklet])
+  segment = np.hstack((v0,v1))
+
+  print(segment)
+  fmt = ('%.3f','%.3f','%d','%.3f','%.3f','%d')
+  np.savetxt(args.output, segment, fmt=fmt)

paper/sections/tutorial.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+import numpy as np
+import tracee
+
+# Load the data table.
+# The table should have three columns.
+filename = 'sample/mockdata_N006F030D500d00_b7e8.txt'
+data = np.loadtxt(filename)
+
+# Generate a parameter set.
+param = tracee.default_parameters()
+param.limit = 10  # Set the minimum number of points to 10.
+
+# Call tracee.extract to identify tracklets.
+# The function returns a list of Tracklet instances.
+# The Tracklet instance contains
+#   - tail: the starting point.
+#   - head: the terminal point.
+#   - members: a list of the associated points.
+tracklet = tracee.extract(data, n_neighbor=3, param=param)

tracee/__init__.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+from fdlsgm import default_parameters
+from .extract import extract, Tracklet
+from .extract import generate_edge
+
+
+__version__ = '0.0.4'
+
+__all__ = [
+    '__version__',
+    'extract',
+    'Tracklet',
+    'generate_edge',
+    'default_parameters'
+]

tracee/extract.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+from dataclasses import dataclass
+from typing import List
+import minimalKNN as knn
+import fdlsgm
+import numpy as np
+
+
+@dataclass
+class Tracklet(object):
+    ''' Tracklet Container
+
+    Atrributes:
+        tail (ndarray):
+            The starting point of the tracklet.
+            The argument should be compatible with an numpy.ndarray, whose
+            number of elements should be three.
+            The array content is expectd to be (x, y, t).
+        head (ndarray):
+            The terminal point of the tracklet.
+            The argument should be compatible with an numpy.ndarray, whose
+            number of elements should be three.
+            The array content is expectd to be (x, y, t).
+        members (ndarray):
+            The associated members of the tracklet.
+            The argument should be a two-dimensional array compatible with an
+            numpy.ndarray. The shape of the array should be (N, 3), where N
+            is the number of the members. Each element should have the
+            (t, y, x)-coordinate of a vertex.
+    '''
+    tail: np.ndarray
+    head: np.ndarray
+    members: np.ndarray
+
+    def __post_init__(self):
+        ''' Validation of the argument is applied here. '''
+        try:
+            self.tail = np.array(self.tail)
+            assert self.tail.shape == (3, )
+        except Exception as e:
+            raise AssertionError(
+                'the starting point should have three elements.') from e
+        try:
+            self.head = np.array(self.head)
+            assert self.head.shape == (3, )
+        except Exception as e:
+            raise AssertionError(
+                'the terminal point should have three elements.') from e
+        try:
+            self.members = np.array(self.members)
+            assert self.members.ndim == 2
+            assert self.members.shape[1] == 3
+        except Exception as e:
+            raise AssertionError(
+                'the shape of the members should be (N, 3).') from e
+
+
+def generate_edge(vertex: np.ndarray,
+                n_neighbor: int,
+                max_velocity: float):
+    ''' generate edges using k-nearest neighbor graph
+
+    Parameters:
+        vertex (ndarray):
+            A list of extracted sources. The shape should be (N, 3),
+            where N is the number of the sources.
+            Each element should be an array of (x, y, t), where t is the
+            timestamp, y and x are the location of the source.
+        n_neighbor (int):
+            The number of neighbors (k).
+        max_velocity (float):
+            Remove the edges whose collesponding velocities are larger
+            than this velocity.
+
+    Return:
+        An ndarray that contains pairs of the vertex indices. The first index
+        indicates the starting vertex, while the second does the terminal.
+    '''
+    ## edges:
+    ##   An ndarray with the shape of (N, 2), where N is the number of edges.
+    ##   The first element is the index of the starting vertex, while the
+    ##   second element is the index of the end vertex.
+    edge = np.array(knn.compressed_graph(vertex, n_neighbor))
+    ## return an empty list when no edge is found.
+    if len(edge) == 0:
+        return np.ndarray((0, 2), float)
+
+    ## drop edges with the same z-location.
+    z, y, x = vertex[:, 2], vertex[:, 1], vertex[:, 0]
+    edge = edge[z[edge[:, 0]] != z[edge[:, 1]]]
+    ## return an empty list when no edge remains.
+    if len(edge) == 0:
+        return np.ndarray((0, 2), float)
+
+    ## drop edges faster than max_velocity.
+    dx  = x[edge[:, 0]] - x[edge[:, 1]]
+    dy  = y[edge[:, 0]] - y[edge[:, 1]]
+    dz  = z[edge[:, 0]] - z[edge[:, 1]]
+    sqv = (dx * dx + dy * dy) / (dz * dz)
+    edge = edge[sqv < max_velocity ** 2]
+    ## return an empty list when no edge remains.
+    if len(edge) == 0:
+        return np.ndarray((0, 2), float)
+
+    ## drop edges faster than max_velocity.
+    dx  = x[edge[:, 0]] - x[edge[:, 1]]
+    dy  = y[edge[:, 0]] - y[edge[:, 1]]
+    dz  = z[edge[:, 0]] - z[edge[:, 1]]
+    sqv = (dx * dx + dy * dy) / (dz * dz)
+    edge = edge[sqv < max_velocity ** 2]
+    ## return an empty list when no edge remains.
+    if len(edge) == 0:
+        return np.ndarray((0, 2), float)
+
+    ## correct the direction of the edges.
+    inv = z[edge[:, 0]] > z[edge[:, 1]]
+    edge[inv, :] = edge[inv, ::-1]
+
+    return edge
+
+
+def extract(vertex: np.ndarray, *,
+            n_neighbor: int=3,
+            max_velocity: float=200.0,
+            param: fdlsgm.solve_parameters=None):
+    ''' extract tracklets from a source list.
+
+    Parameters:
+      vertex (ndarray):
+          A list of extracted sources. The shape should be (N, 3),where N is
+          the number of the sources.
+          Each element should be an array of (x, y, t), where t is the
+          timestamp, y and x are the location of the source.
+      n_neighbor (int):
+          The number of neighbors (k).
+      max_velocity (float):
+          Remove the edges whose collesponding velocities are larger than this
+          velocity.
+      param (solve_parameters):
+          The parameters of the fdlsgm.solve function.
+
+    Return:
+      A list of Tracklet instances.
+    '''
+    ## edges:
+    ##   An ndarray with the shape of (N, 2), where N is the number of edges.
+    ##   The first element is the index of the starting vertex, while the
+    ##   second element is the index of the end vertex.
+    edge = generate_edge(vertex, n_neighbor, max_velocity)
+    ## return an empty list when no edge is found.
+    if len(edge) == 0:
+        return list()
+
+    ## v0: the vertices of starting points.
+    ## v1: the vertices of terminal points.
+    v0, v1 = vertex[edge[:, 0], :], vertex[edge[:, 1], :]
+    ## els:
+    ##   An array of elemental line segments with the shape of (N, 6), where N
+    ##   is the number of ELSs. The element should be (t0, y0, x0, t1, y1, x1).
+    ##   The first three elements are the vertex of the starting point, while
+    ##   the second three elements are the vertex of the terminal point.
+    els = np.hstack((v0, v1))
+
+    if param is None:
+        param = fdlsgm.default_parameters()
+
+    ## baseline:
+    ##   An array of baselines.
+    ##   The baseline class has four attributes:
+    ##     - vertex0 (starting point)
+    ##     - vertex1 (terminal point)
+    ##     - size (number of vertices)
+    ##     - elements (indexes of associated vertex)
+    baseline = fdlsgm.solve(els, param)
+
+    return [
+        Tracklet(b.vertex0, b.vertex1, vertex[np.unique(edge[b.elements, :])])
+        for b in baseline]

tracee-0.0.4.dist-info/METADATA

@@ -0,0 +1,49 @@
+Metadata-Version: 2.4
+Name: tracee
+Version: 0.0.4
+Author-email: Ryou Ohsawa <ryou.ohsawa@nao.ac.jp>
+Maintainer-email: Ryou Ohsawa <ryou.ohsawa@nao.ac.jp>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: minimalKNN>=0.5
+Requires-Dist: fdlsgm>=0.5.5
+Dynamic: license-file
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![CodeQL](https://github.com/astronasutarou/tracee/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/astronasutarou/tracee/actions/workflows/github-code-scanning/codeql)
+
+# Tracklet Extraction Engine
+
+This package provides a function to retrieve _tracklets_ from a list of _vertices_ in a three-dimensional space. The function find a set of linearly aligned vertices in the list and derive a line segment (tracklet) to approximate the vertex distribution.
+
+
+## Overview
+
+The module provides a class `Tracklet` and a function `extract`. The `extract` function receives a list of vertices as `numpy.ndarray`. The array shape should be `(n,6)`, where _n_ is the number of vertices. Then, a list of `Tracklets` instances are returned. Some tutorials are available in [notebook][notebook].
+
+[notebook]: https://bitbucket.org/ryou_ohsawa/tracee/src/master/notebook/
+
+
+## Requiremnts
+The package `tracee` depends on the following packages. Both packages are available in [PyPi][pypi]. Installation on Ubuntu 18.04 was confirmed. If you have any troubles in installation, please contact to the developer.
+
+- [fdlsgm>=0.5.5][fdlsgm]
+- [minimalKNN>=0.5][minimalKNN]
+
+
+[pypi]: https://pypi.org/
+[fdlsgm]: https://pypi.org/project/fdlsgm/
+[minimalKNN]: https://pypi.org/project/minimalKNN/

tracee-0.0.4.dist-info/RECORD

@@ -0,0 +1,11 @@
+notebook/sample/generate_knn-graph.py,sha256=XqQ_onhr1NHtG7qCbyvXwEr_B2DPOyVo3hM2Ctt9M2M,703
+notebook/sample/generate_mock_data.py,sha256=h9AoIgY2RpgAf42QsRmSTkJuJ8wH2ZW20S14CeAcNTc,3397
+notebook/sample/generate_tracklet.py,sha256=AYFoVzv7EUZwvkotCn875HRgnfkYFSXAQYmVTZtyY6I,945
+paper/sections/tutorial.py,sha256=EEy49NyVCRJwYtrI59WleR-s7DuJQmBmHT-ufD-nm4E,652
+tracee/__init__.py,sha256=QDeurTvO10gMzNqcMY3ulKPOFZYpxD29qfZXCMGU75c,293
+tracee/extract.py,sha256=pfCrcOq7ai0NeFVt88O0d7IchPQzQsmveYwFDT0B3pQ,6578
+tracee-0.0.4.dist-info/licenses/LICENSE,sha256=o3iPJukEaPov0meAAzJg7PbMOVpTYf0dkEIhoQXbBjs,1051
+tracee-0.0.4.dist-info/METADATA,sha256=Y_innNrmnzmjsPUq2uA9Ej5fxkTPNNexe0N5s6cgFg8,2282
+tracee-0.0.4.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+tracee-0.0.4.dist-info/top_level.txt,sha256=s9tx7iYNwLQ1B922dr6ewoBc2l1nhO71ehJjCR2jn5E,28
+tracee-0.0.4.dist-info/RECORD,,

tracee-0.0.4.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tracee-0.0.4.dist-info/licenses/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2021 Ryou Ohsawa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

tracee-0.0.4.dist-info/top_level.txt

@@ -0,0 +1,4 @@
+build
+notebook
+paper
+tracee