# Procedures for creating examples of contacts between paths.
# Last edited on 2021-10-03 12:52:30 by stolfi

import contact_example_IMP
import move
import move_parms
import path
import pyx

# CONTACTS

# SAMPLE CONTACTS FOR THE UNIT TEST PROGRAM

# These test data assume that the width of the filling trace is 1.0 mm, since
# then the nominal sausages of the sides actually touch each other.

def misc_A(mp_trace):
  # Returns a single contact {ct} between two new traces.
  #
  # The moves {side(ct,i)} are
  #
  #   i pini  pfin
  #   - ----- -----
  #   0 (1,1) (4,1)
  #   1 (2,2) (5,2)
  #
  # The endpoints of the contact are {(2,1.5)} and {(4,1.5)}.
  return contact_example_IMP.misc_A(mp_trace)

def misc_B(mp_trace, mp_jump):
  # Returns a list {CTS} of eight contacts between the ten traces of the
  # five oriented paths created by {path_example.misc_E} with
  # aruments {mp_trace, mp_jump}. Also returns the list {OPHS} of those
  # oriented paths and the list {TRS} of those ten traces.
  # 
  # The sides {side(CTS[k],i)} of the contacts, and their midpoints, are
  #
  #   k side0  side1  pmid       obs
  #   - ------ ------ ---------- -----
  #   0 TRS[0] TRS[1] (2.5, 3.5)
  #   1 TRS[1] TRS[2] (4.0, 3.5) single point
  #   2 TRS[0] TRS[2] (3.5, 3.0) single point
  #   3 TRS[2] TRS[3] (%%%, 2.0) 
  #   4 TRS[1] TRS[4] (5.0, 4.5) single point
  #   5 TRS[7] TRS[9] (3.5, 7.5)
  #   6 TRS[8] TRS[9] (5.5, 7.5)
  #   7 TRS[7] TRS[5] (3.5, 6.5)
  #  
  # where "%%%" means a bit more than 5.0.
  #
  return contact_example_IMP.misc_B(mp_trace, mp_jump)

def misc_C(mp_trace):
  # Creates two serpentine paths side by side, one with horizontal rasters, one with 
  # vertical rasters, and returns a list {CTS} of the contacts between them.
  # Also returns a list {PHS} of the two paths.
  return contact_example_IMP.misc_C(mp_trace)

def misc_F(alt, mp_trace, mp_jump):
  # Returns two results, a {Contact} object {ct} and a {Path} object {ph}.
  #
  # The contact {ct} lies between two adjacent traces of {ph},
  # that is expected to have the largest cooling time mong such 
  # contacts.
  #
  # The path {ph} is generated by {path.example.misc_F} with the 
  # {alt} parameter.
  #
  return contact_example_IMP.misc_F(alt, mp_trace, mp_jump)
 
def misc_K(mp_trace, mp_jump):
  # Returns a list {CTS} of three contacts between three paths, and 
  # the list {OPHS} of those paths.
  # Special for {contact_TST.py}.
  return contact_example_IMP.misc_K(mp_trace, mp_jump)

# TEST PROBLEMS FOR THE HOTPATH HEURISTIC

def two_roads_and_islands(nmv, nmg, nis, mp_cont, mp_fill, mp_jump):
  # Returns two results: a list {BCS} of zero or more {Block} objects,
  # and a list {CTS} of zero or more {Contact} objects.
  #
  # The list {BCS} will have some "raster" blocks and some "island"
  # blocks.
  #
  # The raster blocks will form two parallel vertical roads, each
  # comprising {nmv} horizontal raster lines. There will be {nis}
  # islands arranged in a vertical group at the left of the left road,
  # between the two roads, and at the right of the right road, near the
  # middle.
  #
  # If {nmg} is 1, each raster line will be a separate block, with two
  # possible choices, corresponding to the two orientations.
  #
  # If {nmg} is greater than 1, only {nms} of the raster lines, in the
  # middle of the road, will be blocks by themseves, as above. The other
  # {nmv-nms} raster lines will be fused together into serpentine path
  # blocks of {nmg} rasters each. Each of these blocks will have 4
  # choices: the two possible orders for the rasters (bottom to top, top
  # to bottom) and the two possible orientations for the bottom raster.
  # The number {nms} will be at least 1, and will be such that {nmv-nms}
  # is divisible by {2*nmg}. In particular, if {nmv} is less than
  # {4*nmg+1}, each raster will be a block by itself.
  #
  # All rasters will have width {wdf = width(mp_fill)}, and will be spaced vertically by
  # that amount. The width of each road, the gap between the roads, and
  # the size and spacing of the islands will be fixed multiples of {wdf}. 
  # Some {Move} objects  may be shared by two or more choices of
  # the same block.
  #
  # An island block will have a single choice that is a small circular
  # filled contour. It starts and ends at nearly the same point, so
  # there is no point in adding the reversal. There will be {nis}
  # islands arranged in a vertical group at the left of the left road,
  # between the roads, and at the right of the right road.
  # If the island has any filling, there will be a jump before 
  # each filling element.
  #
  # The {Move_Parms} objects {mp_jump}, {mp_cont}, and {mp_fill} will be
  # used for island jumps, contours, and fillings, respectively.
  #
  # There will be a contact between every pair of consecutive blocks in
  # each road.
  return contact_example_IMP.two_roads_and_islands(nmv, nmg, nis, mp_cont, mp_fill, mp_jump)

# FROM BLOCKS

def raster_raster_contact(oph0, oph1, tclim):
  # Assumes that {oph0} and {oph1} are paths made of horizontal raster
  # lines connected by jumps or links, such that the topmost trace of
  # {oph0} is adjacent to the bottommost trace of {oph1}, and they have
  # overlapping {X} ranges. Creates and returns a new {Contact} object
  # between those two traces.
  # 
  # The contact will be undirected.
  return contact_example_IMP.raster_raster_contact(oph0, oph1, tclim)

def raster_raster_block_contact(bc0, bc1, tclim):
  # ???
  return contact_example_IMP.raster_raster_block_contact(bc0, bc1, tclim)