Initial code

LICENSE

@@ -0,0 +1,20 @@
+Copyright (C) 2019 ariadne-service gmbh
+
+This software is provided 'as-is', without any express or implied
+warranty.  In no event will the authors be held liable for any damages
+arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+1. The origin of this software must not be misrepresented; you must not
+   claim that you wrote the original software. If you use this software
+   in a product, an acknowledgment in the product documentation would be
+   appreciated but is not required.
+2. Altered source versions must be plainly marked as such, and must not be
+   misrepresented as being the original software.
+3. This notice may not be removed or altered from any source distribution.
+
+ariadne-service gmbh ariadne.ai
+Sebastian Spaar sebastian.spaar@ariadne.ai

README.rst

@@ -0,0 +1,76 @@
+===========
+treeconvert
+===========
+
+``treeconvert`` converts NML files [1]_ to SWC [2]_. This allows you to view
+skeletal reconstructions created in (Py)KNOSSOS in viewers for SWC files.
+
+The current version (0.9) is currently a little bit restricted:
+
+- Conversion is only possible from (Py)KNOSSOS NML to SWC, not back.
+- SWC’s *structure identifier* is ``UNDEFINED`` for all edges.
+
+If the NML file consists of multiple trees, a separate SWC file will get
+created for each one.
+
+.. [1] For more information about NML files, visit https://github.com/scalableminds/nml-spec.
+.. [2] http://www.neuronland.org/NLMorphologyConverter/MorphologyFormats/SWC/Spec.html
+
+
+Installation
+============
+
+``treeconvert`` only has a single dependency: ``declxml``. For convenience,
+``declxml`` is included directly inside ``treeconvert``'s source tree.
+
+The ``setup.py`` installs a ``treeconvert`` binary that you can use from your
+``PATH``.
+
+Alternatively, go to `Releases <https://github.com/ariadne-service/treeconvert/releases>`_
+to download a self-contained zip file.
+
+To execute the ``.pyz`` file, execute it with python: ``python3 treeconvert.pyz -h``.
+
+
+Requirements
+============
+
+Minimum Python version is 3.7.
+
+
+Usage
+=====
+
+::
+
+	$ python3 cmutil.pyz -h
+	usage: treeconvert.pyz [-h] --from {NML,PYKNOSSOS_NML} --to {SWC} [--force]
+	                       input_file
+
+	Convert annotation files between various formats.
+
+	positional arguments:
+	  input_file            Input file. Output file will be created automatically
+	                        with extension `.[--to]'.
+
+	optional arguments:
+	  -h, --help            show this help message and exit
+	  --from {NML,PYKNOSSOS_NML}
+	                        input format
+	  --to {SWC}            output format
+	  --force               overwrite existing output files.
+
+	If the output format is SWC, and if there are multiple trees in the input
+	file, treeconvert will create a file for each tree, and append the filename
+	with its index.
+
+There a subtle differences between NML files created from KNOSSOS and those
+created from PyKNOSSOS. Because of this, the input format must either be
+``nml`` or ``pyknossos_nml``.
+
+
+License
+=======
+
+Other than ``declxml`` (released under MIT License), all of ``treeconvert``’s
+files are released under the zlib license (c.f. ``LICENSE``).

setup.py

@@ -0,0 +1,16 @@
+from setuptools import setup
+
+setup(name='treeconvert',
+      version='0.9',
+      description='Convert NML files to SWC files',
+      url='https://github.com/ariadne-service/treeconvert',
+      author='ariadne-service gmbh',
+      author_email='contact@ariadne.ai',
+      license='zlib',
+      packages=['treeconvert'],
+      entry_points={
+          'console_scripts': [
+              'treeconvert = treeconvert.__main__'
+          ]
+      },
+      install_requires=['declxml'])

treeconvert/__main__.py

@@ -0,0 +1,73 @@
+# This file is part of treeconvert.
+#
+# Copyright (C) 2019 ariadne-service gmbh
+#
+# This software is provided 'as-is', without any express or implied
+# warranty.  In no event will the authors be held liable for any damages
+# arising from the use of this software.
+#
+# Permission is granted to anyone to use this software for any purpose,
+# including commercial applications, and to alter it and redistribute it
+# freely, subject to the following restrictions:
+#
+# 1. The origin of this software must not be misrepresented; you must not
+#    claim that you wrote the original software. If you use this software
+#    in a product, an acknowledgment in the product documentation would be
+#    appreciated but is not required.
+# 2. Altered source versions must be plainly marked as such, and must not be
+#    misrepresented as being the original software.
+# 3. This notice may not be removed or altered from any source distribution.
+#
+# ariadne-service gmbh ariadne.ai
+# Sebastian Spaar sebastian.spaar@ariadne.ai
+
+from argparse import ArgumentParser
+from pathlib import Path
+from os.path import isfile
+from sys import exit, stderr
+
+from treeconvert.conversion import FileFormats, nml_to_swc, nml_to_dict
+
+parser = ArgumentParser(
+    description='Convert annotation files between various formats.',
+    epilog='If the output format is SWC, and if there are multiple trees in '
+           'the input file, treeconvert will create a file for each tree, '
+           'and append the filename with its index.'
+)
+parser.add_argument('--from', type=FileFormats.argparse, dest='from_format',
+                    help='input format', required=True,
+                    choices=(FileFormats.NML, FileFormats.PYKNOSSOS_NML))
+parser.add_argument('--to', type=FileFormats.argparse, dest='to_format',
+                    help='output format', required=True,
+                    choices=(FileFormats.SWC,))
+parser.add_argument('--force', action='store_true',
+                    help='overwrite existing output files.')
+parser.add_argument('input_file', type=str,
+                    help='Input file. Output file will be created '
+                         'automatically with extension `.[--to]\'.')
+
+args = parser.parse_args()
+
+input_file = Path(args.input_file)
+with input_file.open() as f:
+    content = f.read()
+
+nml = nml_to_dict(content, args.from_format == FileFormats.PYKNOSSOS_NML)
+
+for i, thing in enumerate(nml['things']):
+    swc = nml_to_swc(nml['things'][i])
+
+    if len(nml['things']) == 1:
+        output_file = f'{input_file.stem}.swc'
+    else:
+        # Append index to filename
+        output_file = f'{input_file.stem}.swc.{i + 1}'
+
+    if args.force is False and isfile(output_file):
+        print(f'There is already a file called {output_file}! '
+              f'Use `--force\' to overwrite it.', file=stderr)
+        exit(-1)
+
+    with open(output_file, 'w') as f:
+        f.write(str(swc))
+        f.write('\n')  # so that file ends with empty line

treeconvert/conversion.py

@@ -0,0 +1,109 @@
+# This file is part of treeconvert.
+#
+# Copyright (C) 2019 ariadne-service gmbh
+#
+# This software is provided 'as-is', without any express or implied
+# warranty.  In no event will the authors be held liable for any damages
+# arising from the use of this software.
+#
+# Permission is granted to anyone to use this software for any purpose,
+# including commercial applications, and to alter it and redistribute it
+# freely, subject to the following restrictions:
+#
+# 1. The origin of this software must not be misrepresented; you must not
+#    claim that you wrote the original software. If you use this software
+#    in a product, an acknowledgment in the product documentation would be
+#    appreciated but is not required.
+# 2. Altered source versions must be plainly marked as such, and must not be
+#    misrepresented as being the original software.
+# 3. This notice may not be removed or altered from any source distribution.
+#
+# ariadne-service gmbh ariadne.ai
+# Sebastian Spaar sebastian.spaar@ariadne.ai
+
+import sys
+from collections import defaultdict, deque
+from enum import Enum
+from itertools import groupby, chain
+from operator import itemgetter
+
+import declxml
+
+from treeconvert.nml import things_processor, pyknossos_things_processor
+from treeconvert.swc import SwcData, Edge
+
+
+class FileFormats(Enum):
+    NML = 'nml'
+    PYKNOSSOS_NML = 'pyknossos_nml'
+    SWC = 'swc'
+
+    def __str__(self):
+        return self.name
+
+    def __repr__(self):
+        return str(self)
+
+    @staticmethod
+    def argparse(s):
+        try:
+            return FileFormats[s.upper()]
+        except KeyError:
+            return s
+
+
+class ParseError(Exception):
+    """Raised when NML XML could not be parsed correctly."""
+
+
+def nml_to_dict(xml_str: str, is_pyknossos=False) -> dict:
+    """Converts NML into a Python dict."""
+    try:
+        _ = declxml.parse_from_string(
+            things_processor if not is_pyknossos else pyknossos_things_processor,
+            xml_str
+        )
+        return _
+    except declxml.XmlError as error:
+        print(error, file=sys.stderr)
+        raise ParseError(str(error))
+
+
+def nml_to_swc(nml: dict) -> SwcData:
+    nodes = {node['id']: node for node in nml['nodes']}
+    targets = defaultdict(list, {
+        target: [edge['source'] for edge in list(edges)]
+        for target, edges in groupby(
+            sorted(nml['edges'], key=itemgetter('target')),
+            itemgetter('target')
+        )})
+    sources = defaultdict(list, {
+        source: [edge['target'] for edge in list(edges)]
+        for source, edges in groupby(
+            sorted(nml['edges'], key=itemgetter('source')),
+            itemgetter('source')
+        )})
+    neighbors = {node: set(sources[node] + targets[node]) for node in chain(nodes)}
+
+    try:
+        first_node = set(nodes.keys() - targets.keys()).pop()
+    except KeyError:
+        # No root node found, so take random node from nml['nodes'].
+        first_node = set(nodes).pop()
+
+    swc = SwcData()
+    swc.append(Edge.from_nml_entry(nodes[first_node], -1))
+
+    next_nodes = deque([first_node])
+    visited = set()
+
+    while len(next_nodes) > 0:
+        node = next_nodes.popleft()
+        visited.add(node)
+
+        for neighbor in neighbors[node]:
+            if neighbor in visited:
+                continue
+            next_nodes.append(neighbor)
+            swc.append(Edge.from_nml_entry(nodes[neighbor], node))
+    return swc