<refentry xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="rt1">
  <refmeta>
    <refentrytitle>ASC2DSP</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo class="source">BRL-CAD</refmiscinfo>
    <refmiscinfo class="manual">BRL-CAD User Commands</refmiscinfo>
  </refmeta>
  
  <refnamediv xml:id="name">
    <refname>asc2dsp</refname>
    <refpurpose>
      convert an ASCII dsp file to the BRL-CAD DSP (Displacement map) binary format
    </refpurpose>
  </refnamediv>
  
  <!-- body begins here -->
  <refsynopsisdiv xml:id="synopsis">
    <cmdsynopsis sepchar=" ">
      <command>rt</command>    
      <arg choice="plain" rep="norepeat"><replaceable>file.asc</replaceable></arg>
      <arg choice="plain" rep="norepeat"><replaceable>file.dsp</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>
  
  <refsection xml:id="description"><info><title>DESCRIPTION</title></info>
    
    <para>
      <emphasis remap="I">Asc2dsp</emphasis> converts ASCII (decimal
      integer) cell (point) files to the binary form of a file in
      BRL-CAD's dsp format.  Pixels are defined by
      whitespace-delimited, unsigned decimal integers in the range 0
      to 2^16-1 (65535).  The output file is in dsp binary format (one
      network unsigned short int per cell (point).
    </para>

    <para>The grid is oriented in the X-Y plane where width is in the
    X direction and length is in the Y direction.  When used to create
    a dsp object im mged, the bottom left cell will have its bottom-left
    corner at X = 0, Y = 0, its bottom at Z = 0, and its top at Z
    equal to the value input in the ASCII file.  Note that entries in the
    ASCII file are read in the same manner as a pix file, i.e., filling the
    grid from bottom to top, left to right, so the first cell defined in the ASCII
    file is the bottom-left cell when the dsp file is imported
    with mged. Note also that white space is ignored so the user
    can lay out the grid row by row to aid visualizing the end product
    (always remembering that the order of the rows will be reversed
    during input by mged).</para>

    <para>An easy way to create the input file for asc2dsp is to first create it
    row by row in natural form with the top row being the desired top row and so on
    in desired viewing order.  Then take the finished file and filter it through
    the Unix utility tac which will reverse the order of the rows (lines).
    </para>

    <para>
      Note the user must ensure that the input file is valid for mged so that width
      times length equals the actual number of cells (points).
    </para>

  </refsection>
  
  <refsection xml:id="see_also"><info><title>SEE ALSO</title></info>
    <para>
      <citerefentry><refentrytitle>tac</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>mged</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
      <citerefentry><refentrytitle>dsp</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
    </para>
  </refsection>
  
  <refsection xml:id="diagnostics"><info><title>DIAGNOSTICS</title></info>
  <para>Error conditions include invalid input characters or an input
  value greater than 65535.
  Descriptive messages are printed on stderr.</para>
  </refsection>
  
  <info><corpauthor>BRL-CAD Team</corpauthor></info>
  
  <refsection xml:id="copyright"><info><title>COPYRIGHT</title></info>
  <para>This software is Copyright (c) 2012-2012 United States Government as
  represented by the U.S. Army Research Laboratory. All rights reserved.</para>
  </refsection>

  <refsection xml:id="bug_reports"><info><title>BUG REPORTS</title></info>
  <para>Reports of bugs or problems should be submitted via electronic
  mail to &lt;devs@brlcad.org&gt;, or via the "cadbug.sh" script.</para>
  </refsection>
</refentry>
